更新记录

1.0.0（2026-11-15）

首个正式版本。基于 WuKongIMSDK 官方 SDK 封装的全端 UTS 插件，以统一 API 适配 App-Android / App-iOS / App-HarmonyOS / H5 / 微信小程序，提供连接管理、文本与图片/视频/文件收发、会话管理、连接状态与发送结果监听。本版本汇总了此前 1.0.0 ~ 1.0.5 的全部变更。

全端支持

• App-Android：接入 WuKongIMAndroidSDK 1.5.5（JitPack），桥接地址提供、连接状态、新消息、发送 ACK 四类监听器。
• App-iOS：接入 WuKongIMSDK 1.1.1（CocoaPods），实现 WKConnectionManagerDelegate / WKChatManagerDelegate。
• App-HarmonyOS：接入 @wukong/wkim 1.1.7（ohpm），配置 INTERNET / GET_NETWORK_INFO 权限与默认会话同步 Provider。
• H5 / 微信小程序：接入 wukongimjssdk 1.3.5（npm）；H5 与小程序合并为 utssdk/web/index.uts 一份实现，由 SDK 按运行时自动选择 WebSocket 实现。
• 各端原生连接状态归一为 7 种统一状态，仅 connected 可发送消息。

连接与消息

• init / connect / disconnect / getVersion：初始化、连接、断开与版本查询。
• sendText(options)：发送文本消息。
• onConnectStatus / onMessage / onSendStatus / offAllListeners：订阅连接状态、新消息与发送结果，支持统一移除监听。

图片 / 视频 / 文件消息

• sendImage / sendVideo / sendFile(options)：五端统一发送媒体消息，参数校验与发送结果回调与 sendText 一致。
• buildMediaPayload / parseMediaContent / mediaDigest：构造、容错解析媒体正文，并生成会话预览文案（[图片] / [视频] / [文件]）。解析为纯字符串扫描，不依赖 JSON.parse，兼容 HarmonyOS 运行时。
• 媒体消息采用「元数据 + 外链」：插件不上传文件，元数据序列化为结构化 JSON 走各端统一的文本正文通道（contentType 保持 1），规避各端自定义正文注册及上传 Provider 的差异。
• Web 端 onMessage 统一补齐 contentType 与 {content, type} 结构的 payload。
• wkim store 同步暴露 sendImage / sendVideo / sendFile，会话列表预览识别媒体消息（显示 [图片] / [视频] / [文件] 而非原始 JSON）。

会话管理

• getConversationList / getTotalUnreadCount：获取最近会话列表与全局未读数。
• deleteConversation / clearConversationUnread：删除会话项（仅隐藏，不删除频道消息）、清除指定会话未读。
• onConversationUpdate / onConversationDelete / offConversationListeners：订阅会话新增/更新与删除，并可独立移除会话监听（不影响长连接）。
• 统一会话模型 WKIMConversation：channelId / channelType / unreadCount / lastMsgTimestamp(ms) / lastContent / lastMessage。

兼容性与稳定性

• 修复 App 端 Number(x) 构造报错：Android 的 Java int/long/byte 与 iOS 的 Swift Int 转 number 统一改用 Number.from()；HarmonyOS 字段本身为 number，直接赋值；Web / 小程序为 JS 运行时保持 Number()。
• 修复 Android 端 Kotlin 编译失败：Java 类/接口改为默认导入（import X from '完整包名.X'），接口方法改用平台类型 Int，WKChannel 构造改用 WKChannelType.PERSONAL/GROUP 常量，移除 number.toByte()。
• 删除 utssdk/mp-weixin 目录，H5 与微信小程序共用 Web 实现；小程序通过根目录 utssdk/index.uts 的 MP-WEIXIN 转调段按 UTS 目录回退规则复用。
• web/package.json 更名为 hetu-wkim-js-runtime，声明为 H5 + 小程序共用依赖；getVersion() 返回 wukongimjssdk-1.3.5。

类型与错误

• interface.uts 统一类型定义：WKIMInitOptions / WKIMSendTextOptions / WKIMSendMediaOptions / WKIMMediaKind / WKIMMediaContent / WKIMConversation 等。
• unierror.uts 统一错误对象与错误码；index.uts 对未适配平台提供兜底，返回 9010003。

平台兼容性

uni-app x(5.33)

其他

hetu-wkim · WuKongIM 全端即时通讯 UTS 插件

基于 WuKongIM 官方 SDK 封装，把 App-Android / App-iOS / App-HarmonyOS / H5 / 微信小程序的原生 SDK 差异收敛为同一套 API：连接管理、文本与图片/视频/文件收发、连接状态与发送结果监听、本地会话管理。

能力边界：本插件只做客户端通信层，不提供 UI、不负责文件上传、不提供账号体系与历史消息接口。uid / token / 网关地址由你的业务服务端下发；历史消息请调用自己的后端接口。

一、兼容性

• HBuilderX ≥ 4.25（onXxx 单回调参数自动 keepAlive，保证监听可持续触发）。
• 不支持 Vue2 / nvue / 其他小程序；未适配平台调用 API 会抛 9010003。
• 主要面向 uni-app x 验证；uni-app Vue3 端同样在兼容表中声明为支持。
• App 端含三方原生依赖，必须制作自定义基座或提交云端打包才能真机运行，标准基座不包含这些依赖。

二、安装与前置条件

1. 将 hetu-wkim 放入项目的 uni_modules 目录，代码中从 @/uni_modules/hetu-wkim 导入。
2. H5 / 微信小程序：安装 JS 依赖 npm install --save-exact wukongimjssdk@1.3.5（在插件的 utssdk/web 目录或项目根，按 HBuilderX 依赖解析方式）；小程序还需在微信开发者工具执行「构建 npm」。
3. App 端：依赖已写在各平台 config.json（JitPack / CocoaPods / ohpm），无需手动集成；直接打自定义基座或云端打包。
4. 服务端：登录成功后下发 uid、token 与网关地址。不要在客户端生成 Token，不要把服务端密钥放进 App。
5. 网络：小程序后台把 WebSocket 地址加入 socket 合法域名（必须 wss:// 且证书有效）；H5 生产环境用 wss:// 并确认反向代理支持 WebSocket Upgrade。

iOS 的 config.json 已配置 pod 'WuKongIMSDK', '1.1.1'，macOS + Xcode 可本地编译；若该 Pod 产物缺少 Modules/module.modulemap，按 UTS iOS 文档 补充。

三、快速开始

import {
  init, connect, disconnect,
  sendText, sendImage, sendVideo, sendFile, parseMediaContent,
  onConnectStatus, onMessage, onSendStatus, offAllListeners,
  type WKIMInitOptions, type WKIMSendTextOptions, type WKIMSendMediaOptions
} from '@/uni_modules/hetu-wkim'

/* 1. 先订阅事件，再连接 */
onConnectStatus((res) => {
  if (res.status === 'connected') {
    // 连接就绪，只有此状态可以发送
  } else if (res.status === 'kicked') {
    // 账号在别处登录，请清理登录态
  }
})
onMessage((msg) => {
  if (msg.isSend) return   // 含本端发出的消息，按需过滤
  const media = parseMediaContent(msg.content)
  if (media != null) {
    // 媒体消息：media.kind / url / name / size ...
  } else {
    console.log(msg.fromUid + ': ' + msg.content)
  }
})
onSendStatus((ack) => {
  console.log(ack.success ? '发送成功' : '发送失败 ' + ack.reasonCode)
})

/* 2. 初始化（参数由业务服务端下发） */
init({
  uid: 'alice',
  token: '<服务端签发>',
  host: 'im.example.com',              // App：域名/IP，不带协议；Harmony 可传 host:port
  port: 5100,                           // App 长连接端口；Harmony 已含端口时可传 0
  wsUrl: 'wss://im.example.com:5200',  // H5 / 小程序使用，App 端忽略
  deviceFlag: 1,                        // 0-App，1-Web，2-PC
  debug: false
} as WKIMInitOptions)

/* 3. 建立连接 */
connect()

/* 4. 收到 connected 后发送；channelType：1-单聊，2-群聊 */

// 4.1 文本
sendText({ channelId: 'bob', channelType: 1, text: '你好，Bob' } as WKIMSendTextOptions)

// 4.2 图片：url 由你的上传接口返回，完整可访问地址
sendImage({
  channelId: 'bob', channelType: 1,
  url: 'https://cdn.example.com/a.jpg',
  name: 'a.jpg', size: 10240,
  width: 720, height: 1280,
  duration: 0, cover: ''                // 图片无时长/封面，传 0 / 空串
} as WKIMSendMediaOptions)

// 4.3 视频：duration 秒，cover 为封面图完整 URL
sendVideo({
  channelId: 'bob', channelType: 1,
  url: 'https://cdn.example.com/v.mp4',
  name: 'v.mp4', size: 5242880,
  width: 1080, height: 1920,
  duration: 15, cover: 'https://cdn.example.com/v-cover.jpg'
} as WKIMSendMediaOptions)

// 4.4 文件：尺寸/时长/封面不适用，统一传 0 / 空串
sendFile({
  channelId: 'bob', channelType: 1,
  url: 'https://cdn.example.com/report.pdf',
  name: 'report.pdf', size: 348160,
  width: 0, height: 0, duration: 0, cover: ''
} as WKIMSendMediaOptions)

/* 5. 页面销毁 / 退出登录 */
disconnect(true)   // true = 断开并清除登录态
offAllListeners()

调用顺序：业务登录 → init → onXxx 订阅 → connect → 等待 connected → 发送 → 退出时 disconnect(true) + offAllListeners()。 切换账号：先 disconnect(true) + offAllListeners()，再重新 init（重复初始化会抛 9010006）。

发送参数要点

• 图片/视频/文件共用 WKIMSendMediaOptions，url 为空抛 9010002；name/size/width/height/duration/cover 为必填字段，未知值用 0 / '' 占位，不能省略。
• 插件不上传文件：示例中的 URL 需先由你的业务上传接口得到（详见「四、图片 / 视频 / 文件消息」）。
• 四种发送共用 onSendStatus 回执；onMessage 会收到本端消息，用 msg.isSend 过滤。
• 类型（WKIMInitOptions 等）是编译期类型，请用 import { type X } 具名导入。

四、图片 / 视频 / 文件消息

WuKongIM 的媒体消息是「元数据 + 外链」：文件由你的业务上传接口上传，插件只发送完整 URL 与元数据。

为避免各端 SDK 自定义正文注册差异，插件把媒体元数据序列化成结构化 JSON，走各端统一的文本正文通道发出（contentType 保持 1）。正文格式：

{"wk_media":1,"kind":"image","url":"https://cdn.example.com/a.jpg","name":"a.jpg",
 "size":10240,"width":720,"height":1280,"duration":0,"cover":""}

发送：sendImage / sendVideo / sendFile 共用 WKIMSendMediaOptions，三种完整示例见「三、快速开始」第 4 步。url 必填且必须是完整地址，为空抛 9010002；发送结果仍由 onSendStatus 推送。

上传参考流程（插件不负责上传）：

// 1. 业务上传接口，例如 POST /basic/file/upload，fileType 1-图片 / 2-视频
// 2. 拿到返回结果后拼成完整 URL（相对路径需加你的资源域名）
const url = 'https://cdn.example.com/upload/2026/11/a.jpg'
// 3. 传给 sendImage / sendVideo / sendFile，见「三、快速开始」

接收与渲染：拿到 WKIMMessage.content（或从历史消息 payload 解出的 content）后用插件提供的解析函数判定：

import { parseMediaContent, mediaDigest } from '@/uni_modules/hetu-wkim'

const media = parseMediaContent(contentText)
if (media == null) {
  // 普通文本
} else {
  // media.kind: 'image' | 'video' | 'file'
  // media.url / name / size / width / height / duration / cover
  // 会话列表预览：mediaDigest(media.kind) -> '[图片]' / '[视频]' / '[文件]'
}

parseMediaContent 为纯字符串扫描实现，不依赖 JSON.parse，兼容 HarmonyOS 运行时。

如果你需要 SDK 原生 contentType = 2(图片) / 5(视频) 的正文，需各端自行注册自定义正文类并实现上传 Provider；本插件不提供该模式。

五、API 一览

连接与消息

会话管理

主要类型

type WKIMInitOptions = {
  uid: string; token: string;
  host: string; port: number; wsUrl: string;
  deviceFlag: number; debug: boolean
}

type WKIMSendTextOptions = { channelId: string; channelType: number; text: string }

type WKIMSendMediaOptions = {
  channelId: string; channelType: number;
  url: string; name: string; size: number;      // size 单位：字节
  width: number; height: number;               // 像素
  duration: number;                            // 视频秒数
  cover: string                                // 视频封面 URL
}

type WKIMMessage = {
  messageId: string; clientMsgNo: string; clientSeq: number; messageSeq: number;
  fromUid: string; channelId: string; channelType: number; contentType: number;
  content: string; payload: string; timestamp: number; status: number; isSend: boolean
}

type WKIMConnectStatus = { status: string; reasonCode: number; reason: string }
type WKIMSendStatus = {
  clientSeq: number; messageId: string; messageSeq: number;
  reasonCode: number; success: boolean
}
type WKIMConversation = {
  channelId: string; channelType: number; unreadCount: number;
  lastMsgTimestamp: number; lastContent: string; lastMessage: WKIMMessage | null
}

status 归一为 connecting | connected | syncing | disconnected | fail | kicked | noNetwork，只有 connected 表示可发送。完整类型定义见 utssdk/interface.uts。

错误码

错误对象遵循 uni 错误码规范（errSubject = 'hetu-wkim'）；连接/发送的实时失败同时通过 onConnectStatus / onSendStatus 推送。

六、发布前检查

• Token 安全：只放内存或受控会话存储，避免出现在 URL、日志与错误上报中。
• Android 混淆：项目启用混淆时按官方 SDK 说明保留 com.xinbida.wukongim.**、net.sqlcipher.**、org.whispersystems.**、org.thoughtcrime.securesms.**。
• HarmonyOS：会话/离线消息同步依赖业务侧 Provider；插件内置返回空会话的默认 syncConversationCallback 仅用于保证连接到达 connected，生产环境请替换为真实业务接口。
• 日志：wukongimjssdk 1.3.5 部分控制台输出不受 debug 控制，可能包含解码后的消息内容，发布前按需脱敏。
• 分端验证：App、H5、小程序是不同运行时，需分别验证 WSS 白名单、证书、前后台切换、断网重连、被踢与账号切换；一端通过不代表全端通过。
• 建议：在业务层建一个应用级 IM 单例统一持有连接与监听，页面只订阅其暴露的状态。

七、隐私与权限

• 插件不采集任何数据；uid / token 由业务服务端下发，插件仅透传。
• App-Android：INTERNET；App-HarmonyOS：INTERNET / GET_NETWORK_INFO；小程序需自行配置 wss 域名白名单。

更新记录见 changelog.md。