277e8ed7c6
- 实现了聊天消息发送功能，支持文本、图片、视频、音频、文件等多种消息类型 - 集成了文件上传下载功能，支持多媒体文件的传输和管理 - 添加了群组管理功能，包括创建群组、成员管理、权限控制等操作 - 实现了好友系统，支持好友添加、删除、分组等功能 - 集成了黑名单管理，提供用户屏蔽和解除屏蔽功能 - 添加了会话管理功能，支持对话列表、未读消息统计等 - 实现了历史消息查询和搜索功能 - 添加了实时连接状态管理和自动重连机制
321 行
6.5 KiB
Markdown
321 行
6.5 KiB
Markdown
# 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}'));
|
||
},
|
||
),
|
||
);
|
||
}
|
||
}
|
||
```
|
