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

# Flutter IM 接入

**模块**：`xuqm_flutter_im` · **最低版本**：Dart 3.0+

---

## 登录

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

await XuqmImSdk().login('user_001', 'your_user_sig_jwt');
```

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

---

## 监听消息

```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');
};
```

---

## 发送消息

```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, '新内容');
```

---

## 会话管理

```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', '未完成的消息');
```

---

## 好友与群组

```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);
```

---

## 历史消息

```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,
);
```

---

## 完整示例

```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}'));
        },
      ),
    );
  }
}
```