6cd938cfbc
- 实现了Android SDK的完整IM功能接口，包括消息、群组、好友、会话等核心功能 - 添加了消息收发、历史记录、撤回编辑等完整的消息操作能力 - 实现了群组管理功能，包括创建、成员管理、权限设置等操作 - 添加了好友关系链管理，支持添加、删除、分组等操作 - 实现了会话管理功能，包括置顶、免打扰、已读状态等 - 添加了黑名单、资料管理、搜索等辅助功能 - 补齐了批量操作接口，提升客户端操作效率 - 实现了WebSocket连接管理和事件监听机制 - 添加了离线消息同步和状态管理功能
299 行
7.1 KiB
Markdown
299 行
7.1 KiB
Markdown
# HarmonyOS SDK 概览
|
||
|
||
**包名**：`@xuqm/harmony-sdk` · **版本**：0.1.0 · **支持**：HarmonyOS NEXT（API 12+）、ArkTS
|
||
|
||
## 功能模块
|
||
|
||
| 模块 | 功能 |
|
||
|------|------|
|
||
| `XuqmSDK` | 全局初始化 |
|
||
| `ImSDK` | 单聊、群聊、消息收发 |
|
||
| `UpdateSDK` | App 版本检查、RN Bundle 热更新 |
|
||
|
||
## 安装
|
||
|
||
在 `oh-package.json5` 中添加：
|
||
|
||
```json
|
||
{
|
||
"dependencies": {
|
||
"@xuqm/harmony-sdk": "0.1.0"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 8. Push 接入
|
||
|
||
HarmonyOS SDK 提供 `PushSDK` 用于注册和注销推送 Token。业务层需在获取到 HarmonyOS 推送服务的 Token 后调用注册接口。
|
||
|
||
```typescript
|
||
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 更新
|
||
|
||
```typescript
|
||
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 热更新
|
||
|
||
```typescript
|
||
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/
|
||
```
|
||
|
||
执行安装：
|
||
|
||
```bash
|
||
ohpm install
|
||
```
|
||
|
||
## 快速接入
|
||
|
||
### 1. 初始化（EntryAbility.onCreate）
|
||
|
||
```typescript
|
||
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 登录
|
||
|
||
```typescript
|
||
import { XuqmSDK, ImSDK } from '@xuqm/harmony-sdk'
|
||
|
||
// 只需要 userId + userSig
|
||
await XuqmSDK.login('user_001', 'your_user_sig_jwt')
|
||
// 如果集成了 ImSDK，XuqmSDK.login 会自动触发 WebSocket 连接
|
||
```
|
||
|
||
### 3. 监听消息
|
||
|
||
```typescript
|
||
ImSDK.addListener({
|
||
onConnected(): void { console.log('WS connected') },
|
||
onDisconnected(reason: string | null): void { },
|
||
onMessage(msg: ImMessage): void { /* 处理消息 */ },
|
||
onError(err: string): void { },
|
||
})
|
||
```
|
||
|
||
### 4. 发送消息
|
||
|
||
```typescript
|
||
// 文本消息
|
||
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. 撤回消息
|
||
|
||
```typescript
|
||
const revoked = await ImSDK.revokeMessage(msg.id)
|
||
```
|
||
|
||
### 6. 群聊
|
||
|
||
```typescript
|
||
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. 检查更新
|
||
|
||
```typescript
|
||
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 示例
|
||
|
||
```typescript
|
||
@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` 中添加必要权限：
|
||
|
||
```json
|
||
{
|
||
"requestPermissions": [
|
||
{ "name": "ohos.permission.INTERNET" },
|
||
{ "name": "ohos.permission.GET_NETWORK_INFO" }
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 8. Push 接入
|
||
|
||
HarmonyOS SDK 提供 `PushSDK` 用于注册和注销推送 Token。业务层需在获取到 HarmonyOS 推送服务的 Token 后调用注册接口。
|
||
|
||
```typescript
|
||
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 更新
|
||
|
||
```typescript
|
||
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 热更新
|
||
|
||
```typescript
|
||
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 的整包更新只提供应用市场跳转，不提供本地安装包下载。
|
