XuqmGroup-Web/docs-site/docs/vue3/index.md

# Vue3 SDK 概览

**包名**：`@xuqm/vue3-sdk` · **版本**：0.1.0 · **支持**：Vue 3.4+、Vite 5+

## 功能模块

| 导出 | 功能 |
|------|------|
| `useXuqm()` | 全局初始化 Composable |
| `useIm()` | IM 单聊/群聊响应式状态 |
| `useUpdate()` | 版本检查与热更新 |
| `XuqmProvider` | 可选根组件（自动初始化）|

## 安装

```bash
npm install @xuqm/vue3-sdk
```

从私有 Nexus 安装时，在 `.npmrc` 中添加：

```
@xuqm:registry=https://nexus.xuqinmin.com/repository/npm-hosted/
```

## 快速接入

### 1. 全局初始化（main.ts）

```ts
import { createApp } from 'vue'
import { createXuqm } from '@xuqm/vue3-sdk'
import App from './App.vue'

const app = createApp(App)

app.use(createXuqm({
  appKey:     'your_app_key',
  debug:      import.meta.env.DEV,
}))

app.mount('#app')
```

### 2. IM 登录与消息监听

```vue
<script setup lang="ts">
import { onMounted, onUnmounted } from 'vue'
import { useIm } from '@xuqm/vue3-sdk'

const { messages, connected, login, sendMessage, revokeMessage } = useIm()

onMounted(() => login('user_001', '张三'))
</script>

<template>
  <div>
    <span :class="connected ? 'green' : 'gray'">
      {{ connected ? '已连接' : '未连接' }}
    </span>
    <div v-for="msg in messages" :key="msg.id">
      <b>{{ msg.fromUserId }}</b>: {{ msg.content }}
    </div>
  </div>
</template>
```

### 3. 发送消息

```ts
// 文本
await sendMessage('user_002', 'SINGLE', 'TEXT', 'Hello!')

// 图片
await sendMessage('user_002', 'SINGLE', 'IMAGE', JSON.stringify({
  url: 'https://cdn.example.com/img.jpg',
  width: 1200, height: 800,
}))
```

### 4. 撤回消息

```ts
const revoked = await revokeMessage(msg.id)
```

### 5. 群聊

```ts
const { createGroup, listGroups, subscribeGroup, groupMessages } = useIm()

// 创建群
const group = await createGroup('开发群', ['user_001', 'user_002'])

// 订阅群消息
subscribeGroup(group.id)

// 发群消息
await sendMessage(group.id, 'GROUP', 'TEXT', '大家好')
```

### 6. 检查 App/RN 更新

```ts
import { useUpdate } from '@xuqm/vue3-sdk'

const { checkAppUpdate, checkRNUpdate } = useUpdate()

const appInfo = await checkAppUpdate(1)       // 当前 versionCode
const rnBundle = await checkRNUpdate('home', '1.0.0')
```

## 响应式状态

`useIm()` 返回的响应式 ref：

```ts
const {
  messages,      // Ref<ImMessage[]>  单聊消息列表
  groupMessages, // Ref<ImMessage[]>  当前群消息列表
  connected,     // Ref<boolean>      WS 连接状态
  currentUser,   // Ref<string | null> 当前登录用户
} = useIm()
```

## 消息气泡组件（内置）

SDK 内置基础气泡组件，开箱即用：

```vue
<script setup lang="ts">
import { ImMessageBubble } from '@xuqm/vue3-sdk'
</script>

<template>
  <ImMessageBubble
    v-for="msg in messages"
    :key="msg.id"
    :message="msg"
    :is-own="msg.fromUserId === currentUser"
    @revoke="revokeMessage(msg.id)"
  />
</template>
```