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

# Flutter SDK 概览

**包名**：`xuqm_flutter_sdk` · **版本**：0.2.x · **语言**：Dart

`xuqm_flutter_sdk` 是 XuqmGroup 的 Flutter 端统一入口，通过 MethodChannel 桥接原生能力，同时提供纯 Dart 实现的 IM HTTP API。

---

## 功能模块

| 模块 | 包 | 功能 |
|------|-----|------|
| `xuqm_flutter_common` | `packages/common` | 初始化、网络、配置管理 |
| `xuqm_flutter_im` | `packages/im` | 单聊、群聊、消息收发、会话、好友、群组 |
| `xuqm_flutter_push` | `packages/push` | 设备 Token 注册、厂商检测（Android）/ APNs（iOS）|
| `xuqm_flutter_update` | `packages/update` | App 版本检查、商店跳转、APK 下载（Android）|

---

## 安装

SDK 通过 Gitea Git 仓库发布，在 `pubspec.yaml` 中配置：

```yaml
dependencies:
  xuqm_flutter_sdk:
    git:
      url: https://xuqinmin.com/xuqinmin12/XuqmGroup-FlutterSDK.git
      ref: v0.2.0
```

> Gitea Package Registry 暂不支持 Dart/Flutter 包格式，因此通过 Git Tag 方式发布。

---

## 快速接入

### 1. 初始化

```dart
import 'package:xuqm_flutter_sdk/xuqm_flutter_sdk.dart';

await XuqmSDK.initialize(XuqmInitOptions(
  appKey: 'your_app_key',
  debug: true,
));
```

初始化时会自动向服务端请求远程配置（IM API 地址等），若网络异常则回退到内置默认值。


```dart
XuqmSDK.init(XuqmInitOptions(appKey: 'your_app_key'));
```

---

### 2. IM 登录

```dart
import 'package:xuqm_flutter_sdk/xuqm_flutter_sdk.dart';

// 只需要 userId + userSig
await XuqmImSdk().login('user_001', 'your_user_sig_jwt');
```

登录成功后会自动建立 IM 实时连接。

---

### 3. 监听消息

```dart
final im = XuqmImSdk();

im.ws.onConnected = () {
  print('IM 已连接');
};

im.ws.onMessage = (XuqmImMessage msg) {
  print('收到消息: ${msg.msgType} - ${msg.content}');
};

im.ws.onDisconnected = (String? reason) {
  print('IM 断开: $reason');
};
```

---

### 4. 发送消息

```dart
// 发送文本消息
final msg = await im.sendTextMessage(
  'user_002',
  'SINGLE',
  'Hello from Flutter!',
);

// 发送图片消息
final imgMsg = await im.sendMessage(
  'user_002',
  'SINGLE',
  'IMAGE',
  jsonEncode({'url': 'https://cdn.example.com/img.jpg', 'width': 800, 'height': 600}),
);

// 撤回消息
await im.revokeMessage(msg.id);

// 编辑消息
await im.editMessage(msg.id, '新内容');
```

---

### 5. 会话管理

```dart
// 会话列表
final conversations = await im.listConversations();

// 置顶会话
await im.setConversationPinned('user_002', 'SINGLE', true);

// 免打扰
await im.setConversationMuted('group_xxx', 'GROUP', true);

// 标记已读
await im.markRead('user_002');

// 设置草稿
await im.setDraft('user_002', 'SINGLE', '未完成的消息');
```

---

### 6. 好友与群组

```dart
// 好友列表
final friends = await im.listFriends();

// 添加好友
await im.addFriend('user_002');

// 移除好友
await im.removeFriend('user_002');

// 创建群组
final group = await im.createGroup('Flutter 群', ['user_001', 'user_002']);

// 群组列表
final groups = await im.listGroups();

// 添加群成员
await im.addGroupMember(group.id, 'user_003');

// 退出群聊
await im.leaveGroup(group.id);
```

---

### 7. 历史消息

```dart
// 单聊历史
final history = await im.fetchHistory('user_002', page: 0, size: 20);

// 群聊历史
final groupHistory = await im.fetchGroupHistory('group_xxx', page: 0, size: 50);

// 定位消息所在页
final page = await im.locateHistoryPage(
  'user_002',
  messageId: 'msg_xxx',
  pageSize: 20,
);
```

---

## Push 接入

```dart
import 'package:xuqm_flutter_sdk/xuqm_flutter_sdk.dart';

// 检测当前设备推送厂商（Android）
final vendor = await XuqmPushSdk.detectVendor();
// 返回：HUAWEI / XIAOMI / OPPO / VIVO / HONOR / FCM / APNS

// 请求原生推送注册
await XuqmPushSdk.requestNativeRegistration();

// 监听原生 Token 回调
XuqmPushSdk.onPushToken.listen((tokenInfo) {
  final token = tokenInfo['token'];
  final vendor = tokenInfo['vendor'];
  print('收到 Push Token: $token, 厂商: $vendor');
  
  // 手动上报到服务端（如需要）
  final pushSdk = XuqmPushSdk();
  await pushSdk.registerToken(
    'user_001',
    token!,
    vendor: vendor,
    platform: 'ANDROID',
  );
});
```

---

## Update 接入

```dart
import 'package:xuqm_flutter_sdk/xuqm_flutter_sdk.dart';

final updateSdk = XuqmUpdateSdk();

// 检查 App 更新
final update = await updateSdk.checkAppUpdate();
if (update.needsUpdate) {
  print('新版本: ${update.versionName}');
  print('更新日志: ${update.changeLog}');
  
  if (update.forceUpdate) {
    // 强制更新
    showForceUpdateDialog(update);
  } else {
    // 可选更新
    showOptionalUpdateDialog(update);
  }
}

// 打开商店 / 应用市场
await updateSdk.openStore(update);

// Android：直接打开 APK 下载链接
await updateSdk.openDownloadUrl(update);
```

开发/测试环境可覆盖版本号：

```dart
XuqmUpdateSdk.devSetAppVersion(100, '1.0.0');
```

---

## 多模块统一登录

无论集成了哪些模块（IM、Push、Update），**初始化和登录永远只做一次**：

```dart
// 初始化
await XuqmSDK.initialize(XuqmInitOptions(appKey: 'your_app_key'));

// 登录（业务登录成功后调用一次）
await XuqmImSdk().login('user_001', 'your_user_sig_jwt');

// 登出
await XuqmImSdk().logout();
```

---

## 完整示例

```dart
import 'dart:convert';
import 'package:flutter/material.dart';
import 'package:xuqm_flutter_sdk/xuqm_flutter_sdk.dart';

class ChatPage extends StatefulWidget {
  @override
  _ChatPageState createState() => _ChatPageState();
}

class _ChatPageState extends State<ChatPage> {
  final im = XuqmImSdk();
  final List<XuqmImMessage> messages = [];

  @override
  void initState() {
    super.initState();
    _init();
  }

  Future<void> _init() async {
    await XuqmSDK.initialize(XuqmInitOptions(appKey: 'your_app_key'));
    await im.login('user_001', 'your_user_sig_jwt');

    im.ws.onMessage = (msg) {
      setState(() => messages.add(msg));
    };
  }

  Future<void> _send(String text) async {
    final msg = await im.sendTextMessage('user_002', 'SINGLE', text);
    setState(() => messages.add(msg));
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('Flutter IM')),
      body: ListView.builder(
        itemCount: messages.length,
        itemBuilder: (context, index) {
          final msg = messages[index];
          return ListTile(title: Text('${msg.fromId}: ${msg.content}'));
        },
      ),
    );
  }
}
```