Electron 从零接入晞晗IM

本页面向 Electron 桌面应用。完成后，Main Process 负责连接账号，Renderer 通过 固定 IPC 查询会话并发送第一条消息。

如果代码运行在普通浏览器中，请改看 Web 接入。

1. 准备接入信息

向服务端负责人领取 Server URL、App ID、当前用户 ID 和一个对端测试用户 ID。 正式环境还需要应用自己的后台提供短期 XHIM 访问凭证。

2. 安装 SDK

npm install @xihansoftware/xhim-electron

安装包必须包含与当前操作系统、CPU 和 Electron 版本匹配的预编译文件。应用开发者 安装失败时先确认拿到的是当前平台的完整 SDK 包。

3. 在 Main Process 连接账号

// main.ts
import { app, BrowserWindow, ipcMain } from 'electron'
import { XHIMElectronClient } from '@xihansoftware/xhim-electron'
import { registerXHIMIpc } from '@xihansoftware/xhim-electron/main'

const client = await XHIMElectronClient.connect({
  server: 'https://im.example.com',
  appId: 'your-app',
  userId: signedInUser.id,
  storageRoot: app.getPath('userData'),
  credentialProvider: accountService.fetchXHIMCredential
})

const stopXHIMIpc = registerXHIMIpc(
  ipcMain,
  client,
  () => BrowserWindow.getAllWindows()
)

每个登录账号只创建一个 XHIMElectronClient。聊天窗口不要单独创建 Client， 也不要直接读取凭证或本地数据库。

4. 在 Preload 暴露固定功能

// preload.ts
import { exposeXHIM } from '@xihansoftware/xhim-electron/preload'

exposeXHIM()

BrowserWindow 保持 contextIsolation: true、nodeIntegration: false。Renderer 只使用 window.xhim，不要向网页暴露 client.raw 或任意 Native 方法名。

5. 在 Renderer 监听变化并发送消息

// renderer.ts
const stopEvents = window.xhim.onEvent(() => {
  conversationStore.reload()
})

const conversationId = await window.xhim.directConversation('bob')
await window.xhim.sendText(conversationId, '你好，晞晗IM')

Bob 使用同一 Server 和 App ID 登录后，会收到数据变化事件。收到通知后重新查询 消息列表，不要在 Renderer 中手工维护另一份消息状态。

6. 窗口关闭、登出和换号

普通聊天窗口关闭时，只取消这个窗口的监听：

stopEvents()

用户真正登出或切换账号时，在 Main Process 释放账号资源：

stopXHIMIpc()
await client.logout()
await client.shutdown()

7. 常用功能入口

任务	Renderer 方法
查询会话	window.xhim.conversations()
查询消息	window.xhim.messages(conversationId)
发送文字消息	window.xhim.sendText(...)
标记会话已读	window.xhim.markConversationRead(...)
查询未读数	window.xhim.totalUnreadCount()
查询在线状态	window.xhim.subscribePresence(...)
查询用户资料	window.xhim.currentUserProfileWithExtension()

完整 Main、Preload、Renderer 方法和错误说明见 SDK API Reference。Renderer 需要更多功能时，应在 registerXHIMIpc 与 Preload 中增加明确的方法和参数校验，不要透传任意调用。

8. 推荐的工程目录

src/
├── main/
│   ├── account-session.ts
│   └── xhim-service.ts
├── preload/
│   └── xhim.ts
└── renderer/
    ├── stores/
    └── pages/

账号登录、凭证和 Client 放在 Main；Preload 只做固定桥接；页面与 UI 状态留在 Renderer。这样可以直接接入现有页面和状态管理代码。

9. 常见问题

启动时提示找不到 Native 模块

当前 SDK 包缺少与你的操作系统、CPU 或 Electron 版本匹配的预编译文件。请更换 完整发行包，不要在业务工程中自行拆分或替换其中的原生文件。

Renderer 中没有 window.xhim

确认 BrowserWindow 加载了当前 Preload 文件，并且 Preload 已调用 exposeXHIM()。

登录后窗口没有刷新

确认 Renderer 注册了 window.xhim.onEvent，并在数据变化后重新查询会话或消息。

是否能直接使用 Web SDK

不建议。Electron 使用桌面 SDK；普通浏览器页面使用 Web SDK。