XuqmGroup-Web/docs-site/docs/h5/im.md

H5 IM 接入

模块：@xuqm/h5-sdk · 功能范围：消息收发、会话管理、好友、群组

---

IM 管理器

import { ImManager } from '@xuqm/h5-sdk'

const im = new ImManager()

// 监听连接状态
im.on('connected', () => console.log('IM 已连接'))
im.on('disconnected', () => console.log('IM 已断开'))

// 监听实时消息
im.on('messages', (msgs) => {
  console.log('收到消息', msgs)
})

// 监听会话列表变化
im.on('conversations', (convs) => {
  console.log('会话列表更新', convs)
})

// 开始连接
im.connect()

---

发送消息

// 发送文本
im.send({
  toId: 'user_002',
  chatType: 'SINGLE',
  msgType: 'TEXT',
  content: 'Hello H5!',
})

发送文件消息（自动上传）

SDK 内部自动上传文件到文件服务器，无需调用方手动上传。

import { sendImageMessage, sendFileMessage } from '@xuqm/h5-sdk'

// 发送图片（从 input 元素获取）
const file = document.querySelector('input[type="file"]').files[0]
await sendImageMessage('user_002', 'SINGLE', file, 800, 600)

// 发送文件
await sendFileMessage('user_002', 'SINGLE', file)

---

核心 API

事件订阅

事件	回调签名	说明
connected	() => void	IM 实时连接已建立
disconnected	() => void	IM 实时连接已断开
messages	(msgs: ImMessage[]) => void	收到新消息
conversations	(convs: ConversationData[]) => void	会话列表变化
error	(err: Error) => void	发生错误

im.on('conversations', (convs) => {
  // 更新 UI
})
im.off('conversations', handler)  // 取消订阅

状态属性

im.connected      // boolean，是否已连接
im.messages       // ImMessage[]，当前消息列表
im.conversations  // ConversationData[]，当前会话列表
im.error          // Error | null，最近错误

HTTP API

所有 IM 功能均通过纯函数暴露：

import {
  sendMessage,
  sendTextMessage,
  sendImageMessage,
  sendVideoMessage,
  sendFileMessage,
  sendAudioMessage,
  fetchHistory,
  fetchGroupHistory,
  listConversations,
  markRead,
  listFriends,
  addFriend,
  listGroups,
  createGroup,
  // ...
} from '@xuqm/h5-sdk'

---

与框架集成

React

import { useEffect, useState } from 'react'
import { ImManager } from '@xuqm/h5-sdk'

function useIm() {
  const [im] = useState(() => new ImManager())
  const [messages, setMessages] = useState([])
  const [conversations, setConversations] = useState([])

  useEffect(() => {
    im.on('messages', setMessages)
    im.on('conversations', setConversations)
    im.connect()
    return () => {
      im.off('messages', setMessages)
      im.off('conversations', setConversations)
      im.disconnect()
    }
  }, [im])

  return { im, messages, conversations }
}

纯 HTML/JS

<script src="https://dev.xuqinmin.com/docs/h5-sdk/index.umd.js"></script>
<script>
  XuqmH5SDK.init({ appKey: 'your_app_key' })
  XuqmH5SDK.login('user_001', 'userSig')
  const im = new XuqmH5SDK.ImManager()
  im.on('messages', function(msgs) { console.log(msgs) })
  im.connect()
</script>