2c0ac124d7
- 新增 Android SDK 使用文档，包含模块结构、集成方式和快速开始指南 - 添加 SDK API 重设计规范，统一初始化和登录接口设计 - 补充安全设计规范，完善 UserSig 鉴权和敏感数据处理方案 - 创建平台 REST API 规范，定义服务端到服务端的调用接口 - 添加离线推送架构设计，集成各大厂商推送服务与 IM 联动方案
198 行
3.6 KiB
Markdown
198 行
3.6 KiB
Markdown
# XuqmGroup Vue3 SDK 文档
|
||
|
||
> TypeScript · Vue 3.5 · Vite 6 · 发布至 Nexus npm
|
||
|
||
## 安装
|
||
|
||
```bash
|
||
npm install @xuqm/vue3-sdk
|
||
# 或
|
||
yarn add @xuqm/vue3-sdk
|
||
```
|
||
|
||
Vue 3.5+ 作为 peerDependency，不会重复打包。
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
XuqmGroup-Vue3SDK/src/
|
||
├── core/
|
||
│ ├── http.ts # fetch HTTP 客户端
|
||
│ └── sdk.ts # init / setToken / getConfig
|
||
├── im/
|
||
│ ├── ImClient.ts # WebSocket IM 客户端
|
||
│ └── useIm.ts # Vue Composable 封装
|
||
├── types/
|
||
│ └── index.ts # 全部 TypeScript 类型定义
|
||
└── index.ts # 统一导出
|
||
```
|
||
|
||
---
|
||
|
||
## 快速开始
|
||
|
||
### 1. 初始化（main.ts）
|
||
|
||
```typescript
|
||
import { init } from '@xuqm/vue3-sdk'
|
||
|
||
init({
|
||
appKey: 'ak_your_app_key',
|
||
appSecret: 'as_your_app_secret',
|
||
debug: import.meta.env.DEV,
|
||
})
|
||
```
|
||
|
||
### 2. 设置 Token
|
||
|
||
```typescript
|
||
import { setToken } from '@xuqm/vue3-sdk'
|
||
|
||
// 登录后
|
||
setToken('eyJ...')
|
||
|
||
// 登出
|
||
setToken(null)
|
||
```
|
||
|
||
---
|
||
|
||
## HTTP 客户端
|
||
|
||
```typescript
|
||
import { http } from '@xuqm/vue3-sdk'
|
||
|
||
// 自动附加 Bearer Token，统一解析 ApiResponse
|
||
const user = await http.get<UserInfo>('/api/user/profile')
|
||
const result = await http.post<LoginResp>('/api/auth/login', { account, password })
|
||
```
|
||
|
||
---
|
||
|
||
## IM 模块
|
||
|
||
### useIm Composable（推荐）
|
||
|
||
```vue
|
||
<script setup lang="ts">
|
||
import { useIm } from '@xuqm/vue3-sdk'
|
||
|
||
const { connect, send, revoke, disconnect, messages, connected, error } = useIm()
|
||
|
||
// 在 onMounted 后连接
|
||
onMounted(() => connect())
|
||
// onUnmounted 自动调用 disconnect()
|
||
|
||
function handleSend(text: string) {
|
||
send({
|
||
toId: 'user_002',
|
||
chatType: 'SINGLE',
|
||
msgType: 'TEXT',
|
||
content: text,
|
||
})
|
||
}
|
||
</script>
|
||
|
||
<template>
|
||
<div>
|
||
<span>{{ connected ? '已连接' : '未连接' }}</span>
|
||
<div v-for="msg in messages" :key="msg.id">
|
||
<b>{{ msg.fromId }}</b>: {{ msg.content }}
|
||
</div>
|
||
</div>
|
||
</template>
|
||
```
|
||
|
||
### ImClient（底层，手动管理）
|
||
|
||
```typescript
|
||
import { ImClient } from '@xuqm/vue3-sdk'
|
||
|
||
const im = new ImClient()
|
||
|
||
im.on('connected', () => console.log('connected'))
|
||
im.on('message', (msg) => console.log(msg))
|
||
im.on('revoke', ({ msgId }) => console.log('revoked', msgId))
|
||
im.on('disconnected', (code, reason) => console.log(code, reason))
|
||
im.on('error', (e) => console.error(e))
|
||
|
||
im.connect()
|
||
|
||
// 发送
|
||
im.send({ toId: 'user_002', chatType: 'SINGLE', msgType: 'TEXT', content: 'Hi!' })
|
||
|
||
// 撤回
|
||
im.revoke('msg-uuid')
|
||
|
||
// 断开
|
||
im.disconnect()
|
||
```
|
||
|
||
### 消息类型
|
||
|
||
```typescript
|
||
type MsgType =
|
||
| 'TEXT' | 'IMAGE' | 'VIDEO' | 'AUDIO' | 'FILE'
|
||
| 'CUSTOM' | 'LOCATION' | 'NOTIFY' | 'RICH_TEXT'
|
||
| 'CALL_AUDIO' | 'CALL_VIDEO' | 'FORWARD'
|
||
|
||
type ChatType = 'SINGLE' | 'GROUP'
|
||
```
|
||
|
||
### ImMessage 结构
|
||
|
||
```typescript
|
||
interface ImMessage {
|
||
id: string
|
||
fromId: string
|
||
toId: string
|
||
chatType: ChatType
|
||
msgType: MsgType
|
||
content: string
|
||
extra?: string
|
||
revoked: boolean
|
||
createdAt: string
|
||
}
|
||
```
|
||
|
||
### 自动重连
|
||
|
||
断线后指数退避重连：3s → 6s → 12s → 最大 30s。`disconnect()` 后停止，`useIm()` 在 `onUnmounted` 中自动调用。
|
||
|
||
---
|
||
|
||
## 完整类型导出
|
||
|
||
```typescript
|
||
import type {
|
||
SDKConfig,
|
||
ImMessage,
|
||
SendMessageParams,
|
||
ImEventMap,
|
||
MsgType,
|
||
ChatType,
|
||
ApiResponse,
|
||
} from '@xuqm/vue3-sdk'
|
||
```
|
||
|
||
---
|
||
|
||
## 构建
|
||
|
||
```bash
|
||
# 类型检查
|
||
npm run type-check
|
||
|
||
# 构建（输出 dist/index.es.js + dist/index.cjs.js + dist/index.d.ts）
|
||
npm run build
|
||
```
|
||
|
||
## 发版
|
||
|
||
```bash
|
||
# 确认 .npmrc 指向 https://nexus.xuqinmin.com/repository/npm-hosted/
|
||
npm login --registry=https://nexus.xuqinmin.com/repository/npm-hosted/
|
||
npm run build
|
||
npm publish
|
||
```
|
