XuqmGroup-Web/docs-site/docs/harmony/index.md

HarmonyOS SDK 概览

包名：@xuqm/harmony-sdk · 版本：0.1.0 · 支持：HarmonyOS NEXT（API 12+）、ArkTS

功能模块

模块	功能
XuqmSDK	全局初始化
ImSDK	单聊、群聊、消息收发
UpdateSDK	App 版本检查、RN Bundle 热更新

安装

在 oh-package.json5 中添加：

{
  "dependencies": {
    "@xuqm/harmony-sdk": "0.1.0"
  }
}

---

8. Push 接入

HarmonyOS SDK 提供 PushSDK 用于注册和注销推送 Token。业务层需在获取到 HarmonyOS 推送服务的 Token 后调用注册接口。

import { PushSDK } from '@xuqm/harmony-sdk'

// 注册 Push Token（在获取到系统推送 Token 后调用）
await PushSDK.registerToken('harmony_push_token', 'user_001')

// 登出时注销 Token
await PushSDK.unregisterToken('harmony_push_token')

HarmonyOS 推送 Token 通过系统 Push Kit 获取，具体接入请参考 HarmonyOS 官方推送文档。vendor 固定为 HARMONY，platform 固定为 harmony。

---

9. 版本更新

HarmonyOS SDK 提供整包检查和 RN Bundle 热更新能力。

9.1 检查 App 更新

import { UpdateSDK } from '@xuqm/harmony-sdk'

const result = await UpdateSDK.checkAppUpdate('your_app_key')
if (result.hasUpdate) {
  console.log('发现新版本:', result.info?.latestVersionCode)
  // HarmonyOS 整包更新只提供应用市场跳转
  if (result.info?.marketUrl) {
    await UpdateSDK.openAppMarket(getContext(this), result.info.marketUrl)
  }
}

9.2 RN Bundle 热更新

const rnResult = await UpdateSDK.checkRNUpdate(
  'your_app_key',
  'home',        // bundle 名称
  1              // 当前 bundle 版本号
)

if (rnResult.hasUpdate) {
  console.log('发现 RN Bundle 更新:', rnResult.info?.bundleVersion)
  
  // 下载 Bundle
  const destPath = await UpdateSDK.downloadRnBundle(
    getContext(this),
    rnResult.info!.downloadUrl,
    'home.bundle'
  )
  console.log('Bundle 下载完成:', destPath)
  // 缓存至本地，由 BundleRuntime 加载
}

与第 7 节「检查更新」中的示例相比，此处展示了 UpdateSDK 的完整独立 API。HarmonyOS 的整包更新只提供应用市场跳转，不提供本地安装包下载。

配置私有仓库（.ohpmrc）：

registry=https://nexus.xuqinmin.com/repository/ohpm-hosted/

执行安装：

ohpm install

快速接入

1. 初始化（EntryAbility.onCreate）

import { XuqmSDK } from '@xuqm/harmony-sdk'

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
    XuqmSDK.init({
      appKey:     'your_app_key',
      debug:      true,
    })
  }
}

2. IM 登录

import { XuqmSDK, ImSDK } from '@xuqm/harmony-sdk'

// 只需要 userId + userSig
await XuqmSDK.login('user_001', 'your_user_sig_jwt')
// 如果集成了 ImSDK，XuqmSDK.login 会自动触发 WebSocket 连接

3. 监听消息

ImSDK.addListener({
  onConnected():         void { console.log('WS connected') },
  onDisconnected(reason: string | null): void { },
  onMessage(msg: ImMessage):  void { /* 处理消息 */ },
  onError(err: string):       void { },
})

4. 发送消息

// 文本消息
const sent = await ImSDK.sendMessage({
  toId:     'user_002',
  chatType: 'SINGLE',
  msgType:  'TEXT',
  content:  'Hello from HarmonyOS!',
})

// 图片消息
const sent = await ImSDK.sendMessage({
  toId: 'user_002', chatType: 'SINGLE',
  msgType: 'IMAGE',
  content: JSON.stringify({ url: 'https://cdn.example.com/img.jpg', width: 800, height: 600 }),
})

5. 撤回消息

const revoked = await ImSDK.revokeMessage(msg.id)

6. 群聊

const group = await ImSDK.createGroup('鸿蒙群', ['user_001', 'user_002'])
ImSDK.subscribeGroup(group.id)
const sent = await ImSDK.sendMessage({ toId: group.id, chatType: 'GROUP', msgType: 'TEXT', content: '大家好' })

7. 检查更新

import { UpdateSDK } from '@xuqm/harmony-sdk'

const appInfo = await UpdateSDK.checkAppUpdate(1)
if (appInfo?.marketUrl) {
  await UpdateSDK.openAppMarket(getContext(this), appInfo.marketUrl)
}

const bundle = await UpdateSDK.checkRNUpdate('home', '1.0.0')
if (bundle) {
  const content = await UpdateSDK.downloadBundle(bundle.downloadUrl)
  // 缓存至本地，由 BundleRuntime 加载
}

Harmony 的整包更新只提供应用市场跳转，不提供本地安装包下载。

ArkUI 示例

@Component
struct ChatView {
  @State messages: ImMessage[] = []

  aboutToAppear() {
    ImSDK.addListener({
      onMessage: (msg) => { this.messages = [...this.messages, msg] },
      onConnected: () => {},
      onDisconnected: () => {},
      onError: () => {},
    })
  }

  build() {
    Column() {
      List() {
        ForEach(this.messages, (msg: ImMessage) => {
          ListItem() {
            Text(`${msg.fromUserId}: ${msg.content}`)
              .fontSize(16)
              .padding(8)
          }
        })
      }
    }
  }
}

权限配置

在 module.json5 中添加必要权限：

{
  "requestPermissions": [
    { "name": "ohos.permission.INTERNET" },
    { "name": "ohos.permission.GET_NETWORK_INFO" }
  ]
}

---

8. Push 接入

HarmonyOS SDK 提供 PushSDK 用于注册和注销推送 Token。业务层需在获取到 HarmonyOS 推送服务的 Token 后调用注册接口。

import { PushSDK } from '@xuqm/harmony-sdk'

// 注册 Push Token（在获取到系统推送 Token 后调用）
await PushSDK.registerToken('harmony_push_token', 'user_001')

// 登出时注销 Token
await PushSDK.unregisterToken('harmony_push_token')

HarmonyOS 推送 Token 通过系统 Push Kit 获取，具体接入请参考 HarmonyOS 官方推送文档。SDK 内部 vendor 固定为 HARMONY，platform 固定为 harmony。

---

9. 版本更新

HarmonyOS SDK 提供整包检查和 RN Bundle 热更新能力。

9.1 检查 App 更新

import { UpdateSDK } from '@xuqm/harmony-sdk'

const result = await UpdateSDK.checkAppUpdate('your_app_key')
if (result.hasUpdate) {
  console.log('发现新版本:', result.info?.latestVersionCode)
  // HarmonyOS 整包更新只提供应用市场跳转
  if (result.info?.marketUrl) {
    await UpdateSDK.openAppMarket(getContext(this), result.info.marketUrl)
  }
}

9.2 RN Bundle 热更新

const rnResult = await UpdateSDK.checkRnUpdate(
  'your_app_key',
  'home',        // bundle 名称
  1              // 当前 bundle 版本号
)

if (rnResult.hasUpdate) {
  console.log('发现 RN Bundle 更新:', rnResult.info?.bundleVersion)

  // 下载 Bundle
  const destPath = await UpdateSDK.downloadRnBundle(
    getContext(this),
    rnResult.info!.downloadUrl,
    'home.bundle'
  )
  console.log('Bundle 下载完成:', destPath)
  // 缓存至本地，由 BundleRuntime 加载
}

与第 7 节「检查更新」中的示例相比，此处展示了 UpdateSDK 的完整独立 API。HarmonyOS 的整包更新只提供应用市场跳转，不提供本地安装包下载。