# im_plugin_tencent_web

**Repository Path**: nx6313/im_plugin_tencent_web

## Basic Information

- **Project Name**: im_plugin_tencent_web
- **Description**: 封装的供 flutter 使用的web版本的腾讯IM web端插件
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-14
- **Last Updated**: 2026-09-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# im_plugin_tencent_web

A Flutter plugin that inherits from Tencent IM

#### 聊天互动使用：[@tencentcloud/lite-chat](https://cloud.tencent.com/document/product/269/75285) （无UI）进行集成

#### 音视频通话使用：[TUICallEngine](https://web.sdk.qcloud.com/component/trtccalling/doc/TUICallEngine/web/zh-cn/tutorial-00-%E5%AE%9E%E7%8E%B0%E5%8F%8C%E4%BA%BA%E9%80%9A%E8%AF%9D.html) （无UI）进行集成

---

## 预览示例
如果您或您的公司有现成可用的 腾讯IM 即时通讯 服务，
那么您可以点击下面的示例去看看效果。

使用 腾讯IM 即时通讯 的相关参数 登录后就能看到效果啦 🤩🤩🤩🤪

放心登录，别担心，因为这只是示例项目，不会记录任何您的个人资料信息，我保证 😁

[👉 点击去查看示例效果](https://im-plugin-tencent-web-example.1823052143.workers.dev/)

🎃🍟😋 如果无法查看，那应该就是当天的免费浏览额度用完了，要不您明天再来？ 🎉

---

## 使用前准备

### 第一步
引入插件包
```dart
dependencies:
  im_plugin_tencent_web: 最新版本号

// 通过命令
flutter pub add im_plugin_tencent_web
```

### 第二步
下载并复制以下文件到项目的 web 目录下

##### [im_plugin.bundle.js](https://gitee.com/nx6313/im_plugin_tencent_web/blob/master/web/im_plugin.bundle.js)

### 第三步
在 web/index.html 的 head之间添加下面的代码

```javascript
<script src="im_plugin.bundle.js" defer></script>
```

---

## 开始使用

共有两种使用方式（选择你需要的方式就可以）

### 仅 API 调用的方式

#### 初始化IM
```dart
import 'package:im_plugin_tencent_web/im_plugin_tencent_web.dart';
import 'package:im_plugin_tencent_web/im/event_chat_listener_config.dart';
import 'package:im_plugin_tencent_web/im/event_call_listener_config.dart';

ImPluginTencentWeb.initSdk(
  sdkAppID: 0,
  initCall: true, // 是否同时初始化 im Call，默认 true
  eventChatListener: EventChatListenerConfig(),
  eventCallListener: EventCallListenerConfig(), // initCall 为 false 时，可以忽略
);
```
[chat 可传入的事件列表](https://web.sdk.qcloud.com/im/doc/v3/zh-cn/module-EVENT.html)

[call 可传入的事件列表](https://web.sdk.qcloud.com/component/trtccalling/doc/TUICallEngine/web/zh-cn/module-TUICallEvent.html)

#### 登录IM
```dart
import 'package:im_plugin_tencent_web/im_plugin_tencent_web.dart';

try {
    await ImPluginTencentWeb.login(
        userID: '',
        userSig: '',
    );
} catch(err) {
    print('登录出错：$err');
}
```

#### 登出IM
```dart
import 'package:im_plugin_tencent_web/im_plugin_tencent_web.dart';

try {
    await ImPluginTencentWeb.logout();
} catch(err) {
  print('登出出错：$err');
}
```

#### 销毁IM
```dart
import 'package:im_plugin_tencent_web/im_plugin_tencent_web.dart';

try {
    await ImPluginTencentWeb.destroy();
} catch(err) {
  print('销毁出错：$err');
}
```

#### 获取会话列表
```dart
import 'package:im_plugin_tencent_web/im_plugin_tencent_web.dart';
import 'package:im_plugin_tencent_web/model/conversation_item_entity.dart';

try {
    final res = await ImPluginTencentWeb.getConversationList();
    List<dynamic> list = res['conversationList'];
    List<MessageItemEntity> getConversationList = list.map((item) => ConversationItemEntity.fromJson(item)).toList();
} catch(err) {
  print('获取会话列表出错：$err');
}
```

#### 清空会话未读消息数
```dart
import 'package:im_plugin_tencent_web/im_plugin_tencent_web.dart';

ImPluginTencentWeb.setMessageRead({
    required String conversationID // 会话ID
});
```

#### 拉取消息列表
```dart
import 'package:im_plugin_tencent_web/im_plugin_tencent_web.dart';
import 'package:im_plugin_tencent_web/model/message_item_entity.dart';

try {
    final res = await ImPluginTencentWeb.getMessageList({
      required String conversationID, // 会话ID
      String? nextReqMessageID // 拉取下一页时传入。传入上一次请求拿到的 nextReqMessageID
    });

    List<dynamic> messageList = res['messageList'];
    String nextReqMessageID = res['nextReqMessageID'];
    List<MessageItemEntity> getMsgList = messageList.map((item) => MessageItemEntity.fromJson(item)).toList();
} catch(err) {
  print('拉取消息列表出错：$err');
}
```

#### 发送消息
```dart
import 'package:im_plugin_tencent_web/im_plugin_tencent_web.dart';
import 'package:im_plugin_tencent_web/im/create_msg_info.dart';
import 'package:im_plugin_tencent_web/model/message_item_entity.dart';

try {
    final res = await ImPluginTencentWeb.sendMessage({
      required CreateMsgType createMsgType, // 发送消息的类型
      required CreateMsgInfo createMsgInfo, // 发送消息的数据构造
      Map<String, dynamic>? options // 发送消息的配置参数
    });

    Map<String, dynamic> msg = Map<String, dynamic>.from(res['message']);
    MessageItemEntity messageInfo = MessageItemEntity.fromJson(msg);
} catch(err) {
  print('发送消息出错：$err');
}
```
[创建消息参考](https://cloud.tencent.com/document/product/269/75316#.E5.8F.91.E9.80.81.E6.B6.88.E6.81.AF)

#### 拨打音视频通话
```dart
import 'package:im_plugin_tencent_web/im_plugin_tencent_web.dart';

try {
    final res = await ImPluginTencentWeb.call({
      required CallType callType,
      required List<String> userIdList, // 邀请列表
      String? chatGroupId, // IM 群组 / 会话 ID
      String? roomId, // 房间号
      String? userData, // 扩展字段: 用于在邀请信令中增加扩展信息
      Map<String, dynamic>? offlinePushInfo
    });
} catch(err) {
  print('拨打音视频通话出错：$err');
}
```

### 带 UI 的使用方式

#### 在使用UI之前， 你必须先进行IM的初始化与登录流程

在登录业务完成后
```dart
import 'package:im_plugin_tencent_web/im/init.dart';
import 'package:im_plugin_tencent_web/im/event_chat_listener_config.dart';
import 'package:im_plugin_tencent_web/im/event_call_listener_config.dart';

try {
  await doImTencentWebPluginInit(
    sdkAppId: 0,
    initCall: true, // 是否初始化音视频通话，默认 true
    eventChatListener: EventChatListenerConfig(), // 可不传。聊天事件监听
    eventCallListener: EventCallListenerConfig(), // 可不传。音视频通话事件监听
    userId, // 登录 userId
    userSig, // 登录 userSig
  );
} catch (err) {
  // 收到 IM 登录异常的情况下，进行进一步处理
  // 比如：提示用户重试 或 提示登录im失败 或 提示登录im的账号信息有误
}
```

在浏览器每次刷新都会执行的地方这样做
```dart
import 'package:im_plugin_tencent_web/im/init.dart';
import 'package:im_plugin_tencent_web/im/event_chat_listener_config.dart';
import 'package:im_plugin_tencent_web/im/event_call_listener_config.dart';

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

  WidgetsBinding.instance.addPostFrameCallback((_) async {
    try {
      // 不需要传入任何参数，此时会从浏览器会话缓存中读取im相关参数，进行im初始化与im自动登录
      await doImTencentWebPluginInit();
      
      // 如果担心用户手贱清除了浏览器的 sessionStorage 缓存导致不传参数的方式调用失败，也可以传入全量的参数
      await doImTencentWebPluginInit(
        sdkAppId: 0,
        initCall: true, // 是否初始化音视频通话，默认 true
        eventChatListener: EventChatListenerConfig(), // 可不传。聊天事件监听
        eventCallListener: EventCallListenerConfig(), // 可不传。音视频通话事件监听
        userId, // 登录 userId
        userSig, // 登录 userSig
      );
    } catch (err) {
      // 收到 IM 登录异常的情况下，进行进一步处理
      // 比如：提示用户后，退出返回到登录页面 或 静默进行 im 的登录重试
    }
  });
}
```

![经典组合UI](https://gitee.com/nx6313/im_plugin_tencent_web/raw/master/example/preview-imgs/default.png)

#### 经典组合UI的使用方式

```dart
import 'package:im_plugin_tencent_web/widget/conversation_list.dart';
import 'package:im_plugin_tencent_web/widget/chat.dart';

Row(
  children: [
    SizedBox(
      width: 300,
      child: ConversationListWidget(),
    ),
    Expanded(
      child: ChatWidget(),
    ),
  ],
)
```
---

![会话列表](https://gitee.com/nx6313/im_plugin_tencent_web/raw/master/example/preview-imgs/conversation.png)

#### 会话列表UI的使用方式

```dart
import 'package:im_plugin_tencent_web/widget/conversation_list.dart';

SizedBox(
    width: 300,
    child: ConversationListWidget(),
)
```
---

![聊天窗口](https://gitee.com/nx6313/im_plugin_tencent_web/raw/master/example/preview-imgs/chat.png)

#### 聊天窗口UI的使用方式

```dart
import 'package:im_plugin_tencent_web/widget/chat.dart';

SizedBox(
    width: 800,
    child: ChatWidget(),
)
```