更新记录

1.0.1-beta4(2026-11-16) 下载此版本

支持蒸汽模式编译

1.0.1-beta3(2026-08-25) 下载此版本

新增变更

  • iOS接口优化

1.0.1-beta2(2026-08-06) 下载此版本

问题修复

  • 修复iOS部分问题
查看更多

平台兼容性

uni-app(3.99)

Vue2 Vue3 Chrome Safari app-vue app-vue插件版本 app-nvue app-nvue插件版本 Android Android插件版本 iOS iOS插件版本 鸿蒙 鸿蒙插件版本
× × × × √ 1.0.0 √ 1.0.0 7.0 1.0.0 13 1.0.0 17 1.0.0
微信小程序 支付宝小程序 抖音小程序 百度小程序 快手小程序 京东小程序 鸿蒙元服务 QQ小程序 飞书小程序 小红书小程序 快应用-华为 快应用-联盟
× × × × × × × × × × × ×

uni-app x(3.99)

Chrome Safari Android iOS 鸿蒙 微信小程序
× × 7.0 13 17 ×

其他

多语言 暗黑模式 宽屏模式 蒸汽模式
√ √ × √

nim-uts-sdk

网易云信 IM SDK 的 UTS 封装,一套代码同时编译到 Android / iOS / Harmony 三端。异步接口统一返回 Promise。

安装

通过 HBuilderX 插件市场安装,插件会落到 uni_modules/nim-uts-sdk/,import 路径即 @/uni_modules/nim-uts-sdk。

三端原生 SDK 依赖由各平台 utssdk/<platform>/config.json 声明,编译时自动合并进 Gradle / Podfile / oh-package.json5,无需手动改原生工程。

快速开始:初始化 + 登录

import {
  initNIMSDK,
  NIMInitSuccess,
  NIMFail,
  V2NIMLoginService,
  V2NIMLoginListener,
  V2NIMDataSyncLevel
} from '@/uni_modules/nim-uts-sdk'

// #ifdef APP-ANDROID
import { AndroidSDKOptions } from '@/uni_modules/nim-uts-sdk'
// #endif
// #ifdef APP-HARMONY
import { HarmonySDKOptions } from '@/uni_modules/nim-uts-sdk'
// #endif

const APP_KEY = 'your_app_key'
const ACCOUNT_ID = 'your_accid'
const TOKEN = 'your_token'

// 1. 按平台构造 SDKOptions(仅 appKey 是必填,其余字段按需设置)
// #ifdef APP-ANDROID
const sdkOptions = new AndroidSDKOptions()
// #endif
// #ifdef APP-HARMONY
const sdkOptions = new HarmonySDKOptions()
// #endif
// #ifdef APP-IOS
const sdkOptions = { appKey: APP_KEY }
// #endif
sdkOptions.appKey = APP_KEY

// 2. 初始化 SDK
initNIMSDK({
  options: sdkOptions,
  success(res: NIMInitSuccess) {
    console.log('init ok', res)
  },
  fail(err: NIMFail) {
    console.error('init fail', err)
  }
})

// 3. 登录
const loginService = new V2NIMLoginService()

loginService.addLoginListener({
  onLoginStatus(status) {
    console.log('login status', status)
  },
  onLoginFailed(error) {
    console.error('login failed callback', error)
  }
} as V2NIMLoginListener)

loginService.login(ACCOUNT_ID, TOKEN, {
  syncLevel: V2NIMDataSyncLevel.V2NIM_DATA_SYNC_TYPE_LEVEL_FULL
}).then((res) => {
  if (res.code == 200) {
    console.log('login ok', res.data)
  } else {
    console.error('login fail', res)
  }
})

三端 login 均返回 Promise<NIMResult<T>>,业务侧按 res.code == 200 判定成功,res.data 取结果。iOS 端 V2NIMLoginAuthType 尚未桥接导出,登录 option 暂只填 syncLevel。

服务一览

通过 new <Service>() 获取实例,常用服务:

服务 说明
V2NIMLoginService 登录、登出、连接状态、监听
V2NIMUserService 用户资料、黑名单、好友
V2NIMFriendService 好友关系管理
V2NIMMessageService 消息收发、查询、撤回、删除
V2NIMMessageCreate 构造文本/图片/语音等消息
V2NIMMessageConvert 消息序列化与反序列化
V2NIMConversationService 会话列表、未读、置顶
V2NIMLocalConversationService 本地会话管理
V2NIMConversationGroupService 会话分组
V2NIMConversationIdUtils 会话 ID 生成与解析(原生 SDK 类名为 V2NIMConversationIdUtil,uts 层统一加 s,见下文「命名差异」)
V2NIMTeamService 群与超级群
V2NIMStorageService 云端存储
V2NIMSettingService 用户设置
V2NIMSubscriptionService 在线状态订阅
V2NIMStatisticsService 统计上报
V2NIMPassthroughService 透传
V2NIMNotificationService 通知

三端服务清单一致,差异只在初始化入参(见上文 // #ifdef 部分)。

Android 蒸汽模式(Vapor)兼容说明

Android 蒸汽模式(manifest.json 的 vapor: true)下,页面逻辑层不再是 UTS 运行时,UTS 插件入口有两类跨桥差异,插件已在本端做了兼容,不需要业务改调用方式(除非用到下面两个新增入口):

  1. 对象参数可以直接传普通对象:addFriend、sendMessage、getMessageList、modifyMessage、addCollection、getTeamInfo、getTeamMemberList、downloadAttachment 等方法的入参,可以继续传声明类型,也可以传字面量/普通 JSON 对象;插件内部用 instanceof UTSJSONObject 分流,typed 对象仍走原强类型路径。
  2. 枚举可以直接传数字:页面里用 1 / 2 代替 V2NIMTeamType.V2NIM_TEAM_TYPE_NORMAL 这类枚举常量(蒸汽模式下 uts-proxy 的枚举值不保证可取到),插件会把数字还原成原生枚举。已覆盖 V2NIMTeamService 全部 teamType / teamRole / chatBannedMode 系列、V2NIMSettingService 免打扰系列、V2NIMConversationService.clearUnreadCountByTypes、V2NIMFriendService.getAddApplicationList、V2NIMLoginService.kickOffline、V2NIMStorageService.downloadAttachment,以及全部消息接口。

两个 Android 专用新增入口(其他端暂未实现,页面里请放在 // #ifdef APP-ANDROID 内):

  • initNIMSDKJson(options: UTSJSONObject, success, fail, complete):初始化配置走 JSON、三个回调走顶层参数。原因是回调如果嵌在对象里,跨桥后会变成 UTSCallback,无法还原成 Kotlin 函数。旧 initNIMSDK(options: NIMInitOptions) 保持不变,标准模式继续可用。
  • V2NIMLoginService.loginWithProviders(accountId, token, option, tokenProvider, loginExtensionProvider):动态 token / 登录扩展 provider 的顶层回调版本。login() 里若仍传 provider 会明确报错并提示改用本方法。

index.d.ts 保持 a3eab36 的强类型声明不变,因此 TS 侧看不到"可以传普通 JSON"这层能力;这是刻意的——其他端尚未实现,声明成联合类型会让其他端编译通过、运行期失败。契约基线变化由 scripts/check_android_dts_signatures.py 守护。

命名差异:V2NIMConversationIdUtils vs 原生 V2NIMConversationIdUtil

三端原生 SDK 中会话 ID 工具类叫 V2NIMConversationIdUtil(单数)。为与 uts 层「工具类用复数」的命名约定一致(参考 V2NIMMessageCreator/V2NIMMessageConverter 两侧并行命名),本插件统一导出为 V2NIMConversationIdUtils(带 s)。

// 正确
import { V2NIMConversationIdUtils } from '@/uni_modules/nim-uts-sdk'
const util = new V2NIMConversationIdUtils()
util.p2pConversationId(accountId)

调用方法与原生 V2NIMConversationIdUtil 完全一致(p2pConversationId / teamConversationId / superTeamConversationId / conversationType / conversationTargetId / isConversationIdValid 等),无逻辑差异,仅类名加 s。

升级原生 SDK 版本

原生 SDK 版本号集中声明在三端各自的 config.json 中,不集中在任何统一文件。升级时改这三处即可:

平台 文件 字段
Android utssdk/app-android/config.json dependencies 数组里 com.netease.nimlib:basesdk:<version> / com.netease.nimlib:chatroom:<version>
iOS utssdk/app-ios/config.json dependencies-pods 里 NIMSDK_LITE 的 version
Harmony utssdk/app-harmony/config.json dependencies 对象里 @nimsdk/* 的版本号

例如从 10.10.10 升到 10.11.0:

// utssdk/app-android/config.json
- "com.netease.nimlib:basesdk:10.10.10",
- "com.netease.nimlib:chatroom:10.10.10"
+ "com.netease.nimlib:basesdk:10.11.0",
+ "com.netease.nimlib:chatroom:10.11.0"

// utssdk/app-ios/config.json
- "version": "10.10.10"
+ "version": "10.11.0"

// utssdk/app-harmony/config.json
- "@nimsdk/nim": "10.10.10",
- "@nimsdk/base": "10.10.10",
+ "@nimsdk/nim": "10.11.0",
+ "@nimsdk/base": "10.11.0",
  ...(其余 @nimsdk/* 同步改)

注意事项:

  • 三端必须升级到同一原生 SDK 版本,避免跨端行为不一致。
  • 升级后建议同步更新 changelog.md 记录版本。
  • 若新版本带来新的初始化字段或 API,需要回到 utssdk/<platform>/ 对应 Service / Options 文件补充桥接字段后才能在 uts 层使用。
  • utssdk/types/CrossPlatformMeta.uts 的 CROSS_PLATFORM_VERSION 是跨端技术栈版本号,与原生 SDK 版本无关,不要混淆。

原生 API 参照文档

uts 层是对原生 V10 SDK 的桥接封装,方法签名与语义以原生为准。遇到字段含义、取值枚举、回调时序等疑问,请对照官方文档:

  • 云信 IM 客户端 API:https://doc.yunxin.163.com/messaging2/client-apis?platform=client

跨端版本标记维护

uts 层向原生 SDK 透传的「跨端技术栈种类」与「跨端技术栈版本号」(v10.10.10+ 原生 SDK 初始化参数)统一由 utssdk/types/CrossPlatformMeta.uts 控制:

  • CROSS_PLATFORM_TYPE — 跨端技术栈种类(当前 112,对应 uni-app-x)
  • CROSS_PLATFORM_VERSION — 跨端技术栈版本号(当前 '1.0.0')

Android、iOS 与 Harmony 三端 init 脚本均 import 该文件并赋给原生 SDK 初始化配置。升级或调整跨端标记时,只需改这一个文件的两行常量,三端自动生效。

不要把 crossPlatformType 写回 package.json:uts 运行时无法读取 package.json,故该字段不再承载于 package.json,而由 CrossPlatformMeta.uts 作为唯一来源。package.json 的 version 是插件自身版本,与 CROSS_PLATFORM_VERSION 是两个独立概念,无需强制同步。

隐私、权限声明

1. 本插件需要申请的系统权限列表:

- android.permission.INTERNET - android.permission.ACCESS_NETWORK_STATE

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明:

插件不采集任何数据

3. 本插件是否包含广告,如包含需详细说明广告表达方式、展示频率:

无

许可协议

MIT协议