H5 SDK 接入指南

包名：@xuqm/h5-sdk · 语言：TypeScript / JavaScript · 格式：ESM + UMD

@xuqm/h5-sdk 是从 Vue3 SDK 提取的纯 JavaScript/TypeScript 核心库，不依赖任何前端框架（Vue/React/Angular 均可使用），可在任何支持 ES6 的浏览器或 H5 环境中运行。

功能范围：仅包含 IM 功能（消息收发、会话管理、好友、群组），不包含 Push 和 Update。

安装

npm install @xuqm/h5-sdk

或 CDN 引入：

<script src="https://dev.xuqinmin.com/docs/h5-sdk/index.umd.js"></script>
<script>
  const { init, ImManager, login } = XuqmH5SDK
</script>

快速接入

1. 初始化

只需传入 appKey，服务器地址由 SDK 内置。

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

init({
  appKey: 'your_app_key',   // 在租户平台创建应用后获得
})

2. 登录

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

await login('user_001', 'your_user_sig_jwt')

3. 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()

4. 发送消息

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

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

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>

4.1 KiB 原始文件 Blame 文件历史 Unescape Escape