SDKsHarmonyOS商业版

事件概览

按应用和账号生命周期注册、使用并清理 HarmonyOS SDK 事件。

sdk.on() 返回一个取消订阅函数。事件处理函数必须保持稳定引用，不要在每次组件更新时重复注册。连接、消息和通话事件适合放在账号级状态层；只影响单个页面的事件应在页面销毁时取消。

事件范围	建议归属页面
连接、Token 和账号下线	认证与管理登录会话
会话列表与未读数	获取会话列表
用户、关系链、群组和成员	对应领域的概览或列表页
普通消息	接收消息
文件上传	上传文件
通话	处理通话事件

监听服务端数据同步

登录后 SDK 会同步 OpenIMServer 数据。reinstalled 表示本轮同步是否发生在重装或本地数据重建场景；同步完成后应重新读取当前界面所需数据。

import sdk, {
  EventOnSyncServerFailedData,
  EventOnSyncServerFinishData,
  EventOnSyncServerProgressData,
  EventOnSyncServerStartData,
  OpenIMSDKEvent,
} from '@openimsdk/imsdk';

const handleSyncStart = (data: EventOnSyncServerStartData): void => {
  setSyncState('syncing', 0, data.reinstalled);
};
const handleSyncProgress = (data: EventOnSyncServerProgressData): void => {
  setSyncState('syncing', data.progress, false);
};
const handleSyncFinish = (data: EventOnSyncServerFinishData): void => {
  setSyncState('ready', 100, data.reinstalled);
  reloadVisibleData();
};
const handleSyncFailed = (data: EventOnSyncServerFailedData): void => {
  setSyncState('failed', 0, data.reinstalled);
};

const unsubscribeSyncStart = sdk.on(OpenIMSDKEvent.EventOnSyncServerStart, handleSyncStart);
const unsubscribeSyncProgress = sdk.on(
  OpenIMSDKEvent.EventOnSyncServerProgress,
  handleSyncProgress,
);
const unsubscribeSyncFinish = sdk.on(OpenIMSDKEvent.EventOnSyncServerFinish, handleSyncFinish);
const unsubscribeSyncFailed = sdk.on(OpenIMSDKEvent.EventOnSyncServerFailed, handleSyncFailed);

export function removeSyncListeners(): void {
  unsubscribeSyncStart();
  unsubscribeSyncProgress();
  unsubscribeSyncFinish();
  unsubscribeSyncFailed();
}

监听本地数据迁移

SDK 升级或本地数据库变化时可能触发迁移。迁移期间不要提前读取依赖完整本地数据的列表。

import sdk, {
  EventOnMigrationFailedData,
  EventOnMigrationProgressData,
  OpenIMSDKEmptyPayload,
  OpenIMSDKEvent,
} from '@openimsdk/imsdk';

const handleMigrationStart = (data: OpenIMSDKEmptyPayload): void => {
  setMigrationState('running', 0, '');
};
const handleMigrationProgress = (data: EventOnMigrationProgressData): void => {
  setMigrationState('running', data.progress, data.message);
};
const handleMigrationFinished = (data: OpenIMSDKEmptyPayload): void => {
  setMigrationState('finished', 100, '');
};
const handleMigrationFailed = (data: EventOnMigrationFailedData): void => {
  setMigrationFailed(data.errCode, data.errMsg);
};

const unsubscribeMigrationStart = sdk.on(
  OpenIMSDKEvent.EventOnMigrationStart,
  handleMigrationStart,
);
const unsubscribeMigrationProgress = sdk.on(
  OpenIMSDKEvent.EventOnMigrationProgress,
  handleMigrationProgress,
);
const unsubscribeMigrationFinished = sdk.on(
  OpenIMSDKEvent.EventOnMigrationFinished,
  handleMigrationFinished,
);
const unsubscribeMigrationFailed = sdk.on(
  OpenIMSDKEvent.EventOnMigrationFailed,
  handleMigrationFailed,
);

export function removeMigrationListeners(): void {
  unsubscribeMigrationStart();
  unsubscribeMigrationProgress();
  unsubscribeMigrationFinished();
  unsubscribeMigrationFailed();
}

退出账号或销毁全局状态层时，分别调用 removeSyncListeners() 和 removeMigrationListeners()。事件可能重复或交错到达，领域数据仍需用用户 ID、conversationID、groupID、groupID:userID 和 clientMsgID 等稳定标识合并。

这个页面有帮助吗？