Flutter聊天室UI组件插件chatroom_uikit的使用

Flutter聊天室UI组件插件chatroom_uikit的使用

English | 中文

ChatroomUIKit

ChatroomUIKit 是专为泛娱乐场景设计的聊天室UI组件库。它通过简化SDK集成、支持定制化以及提供全面文档的方式，为用户提供了良好的API使用体验。

开发环境要求

  • SDK: >=3.0.0 <4.0.0
  • Flutter: >=3.12.0

对于iOS应用：

  • Xcode 13或更高版本
  • iOS 11或更高版本

对于Android应用：

  • minSDKVersion 21

ChatroomUIKit安装

在项目的pubspec.yaml文件中添加以下依赖：

flutter pub add chatroom_uikit

运行示例

运行示例代码：

flutter run example/lib/main.dart

项目结构

以下是项目的目录结构：

.
├── chatroom_localizations.dart         // 国际化工具
├── chatroom_settings.dart              // 组件配置
├── chatroom_uikit.dart                 // ChatroomUIKit组件
├── chatroom_uikit_client.dart          // ChatroomUIKit初始化类
├── service                             // 基础服务组件
│   ├── controllers                     // UI组件协议
│   │   ├── chat_report_controller.dart
│   │   ├── chat_text_editing_controller.dart
│   │   ├── chatroom_controller.dart
│   │   ├── chatroom_message_list_controller.dart
│   │   ├── gift_page_controller.dart
│   │   └── participant_page_controller.dart
│   ├── default
│   │   ├── controllers                 // UI组件协议实现
│   │   │   ├── default_gift_page_controller.dart
│   │   │   ├── default_members_controller.dart
│   │   │   ├── default_message_list_controller.dart
│   │   │   ├── default_mutes_controller.dart
│   │   │   └── default_report_controller.dart
│   │   └── data                        // UI组件数据协议
│   │       ├── gift_entity.dart
│   │       └── user_entity.dart
│   ├── implement                       // 协议实现组件
│   │   ├── chatroom_context.dart
│   │   ├── chatroom_service_implement.dart
│   │   ├── gift_service_implement.dart
│   │   └── user_service_implement.dart
│   └── protocol                        // 业务协议组件
│       ├── chatroom_service.dart
│       ├── gift_service.dart
│       └── user_service.dart
├── ui                                  // 基本UI组件
│   ├── component
│   │   ├── chatroom_gift_list_view.dart
│   │   ├── chatroom_gift_message_list_view.dart
│   │   ├── chatroom_global_broad_cast_view.dart
│   │   ├── chatroom_message_list_view.dart
│   │   ├── chatroom_participants_list_view.dart
│   │   └── chatroom_report_list_view.dart
│   └── widget
│       ├── chat_avatar.dart
│       ├── chat_bottom_sheet.dart
│       ├── chat_bottom_sheet_background.dart
│       ├── chat_dialog.dart
│       ├── chat_input_bar.dart
│       ├── chat_input_emoji.dart
│       ├── chat_more_item_action.dart
│       ├── chat_uikit_button.dart
│       └── custom_tab_indicator.dart
└── utils                               // 工具包
    ├── chatroom_enums.dart
    ├── chatroom_event_item_action.dart
    ├── define.dart
    ├── extension.dart
    ├── icon_image_provider.dart
    ├── image_loader.dart
    ├── language_convertor.dart
    └── time_tool.dart

高级用法

初始化ChatroomUIKit

要初始化ChatroomUIKit，需要从Agora控制台获取App Key。

await ChatroomUIKitClient.instance.initWithAppkey(appKey);

登录ChatroomUIKit

登录时，需要传递在Agora控制台注册用户时输入的用户ID和密码。

try {
  await ChatroomUIKitClient.instance.loginWithPassword(
    userId: userId,
    password: password, // 注册用户时输入的密码。
    userInfo: userInfo, // 符合UserInfoProtocol协议的当前用户对象。默认用户对象为ChatroomUIKit中的`UserEntity`。
  );
} on ChatError catch (e) {
  // 错误处理。
}

或者，您可以使用用户令牌进行登录。为了生成测试用途的临时用户令牌，请访问 Agora文档。

try {
  await ChatroomUIKitClient.instance.loginWithToken(
    userId: userId,
    token: userToken, // 用户令牌。
    userInfo: userInfo, // 符合UserInfoProtocol协议的当前用户对象。默认用户对象为ChatroomUIKit中的`UserEntity`。
  );
} on ChatError catch (e) {
  // 错误处理。
}

切换主题

可以使用ChatUIKitTheme切换ChatroomUIKit内置的light或dark主题。

ChatUIKitTheme(
  color: ChatUIKitColor.light(), // 切换到亮色主题。若要切换到暗色主题，请指定参数为`ChatUIKitColor.dark()`。
  child: child,
),

要调整主题颜色，需要在ChatUIKitColor中定义以下颜色的hue值：

ChatUIKitColor({
  this.primaryHue = 203,
  this.secondaryHue = 155,
  this.errorHue = 350,
  this.neutralHue = 203,
  this.neutralSpecialHue = 220,
  this.barrageLightness = LightnessStyle.oneHundred,
  this.isDark = false,
});

ChatroomUIKit组件

  1. 确保ChatUIKitTheme作为ChatroomUIKit组件的父节点。建议将其设置为项目的根节点。
@override
Widget build(BuildContext context) {
  return MaterialApp(
    builder: (context, child) {
      return ChatUIKitTheme(child: child!);
    },
    home: const MyHomePage(title: 'Flutter Demo Home Page'),
    ...
  );
}
  1. 使用chatroom_uikit前，需要先创建ChatroomController，然后将ChatRoomUIKit设置为当前页面的根节点，并将其他组件作为ChatRoomUIKit的子节点。
// roomId: 聊天室ID。
// ownerId: 聊天室所有者ID。
ChatroomController controller = ChatroomController(roomId: roomId, ownerId: ownerId);

@override
Widget build(BuildContext context) {
  Widget content = Scaffold(
    resizeToAvoidBottomInset: false,
    appBar: AppBar(),
    body: ChatRoomUIKit(
      controller: controller,
      child: (context) {
        // 在子组件中构建页面，如礼物窗口和消息列表页面。
        return ...;
      },
    ),
  );

  return content;
}

ChatroomMessageListView组件

ChatroomMessageListView组件用于展示聊天室内消息。确保此组件是ChatRoomUIKit的子节点。可以在屏幕上添加ChatroomMessageListView并设置其位置：

@override
Widget build(BuildContext context) {
  Widget content = Scaffold(
    resizeToAvoidBottomInset: false,
    appBar: AppBar(),
    body: ChatRoomUIKit(
      controller: controller,
      child: (context) {
        return const Stack(
          children: [
            Positioned(
              left: 16,
              right: 78,
              height: 204,
              bottom: 90,
              child: ChatroomMessageListView(),
            )
            ...
          ],
        );
      },
    ),
  );

  return content;
}

ChatroomMessageListView 提供点击、长按和重绘功能，并允许设置reportController。

const ChatroomMessageListView({
  this.onTap,
  this.onLongPress,
  this.itemBuilder,
  this.reportController,
  this.controller,
  super.key,
});

默认情况下，ChatroomMessageListView 不会显示礼物。要在消息列表中显示礼物，请在ChatRoomSettings中将enableMsgListGift设置为true。

ChatRoomSettings.enableMsgListGift = true;

ChatInputBar组件

ChatInputBar组件用于发送消息。默认情况下，它位于chatroom_uikit中，位置不可配置。此组件可以包含更多点击选项，并且可以在ChatroomUIKit中配置更多点击事件。

// roomId: 聊天室ID。
// ownerId: 聊天室所有者ID。
ChatroomController controller = ChatroomController(roomId: roomId, ownerId: ownerId);

@override
Widget build(BuildContext context) {
  Widget content = Scaffold(
    resizeToAvoidBottomInset: false,
    appBar: AppBar(),
    body: ChatRoomUIKit(
      controller: controller,
      inputBar: ChatInputBar(),
      child: (context) {
        // 在子组件中构建页面，如礼物窗口和消息列表页面。
        return ...;
      },
    ),
  );

  return content;
}

ChatInputBar 允许通过leading和actions添加小部件。可以通过actions添加四个动作。

ChatInputBar({
  this.inputIcon,
  this.inputHint,
  this.leading,
  this.actions,
  this.textDirection,
  this.onSend,
  super.key,
}) {
  assert(
      actions == null || actions!.length <= 4, 'can\'t more than 4 actions');
}

ChatroomGiftListView组件

在选择和发送礼物之前，需要配置礼物。为此，需要在ChatroomController中配置giftControllers，传入一个符合ChatroomGiftPageController协议的实例（DefaultGiftPageController在chatroom_uikit中可用）。

ChatroomController controller = ChatroomController(
      roomId: widget.roomId,
      ownerId: widget.ownerId,
      giftControllers: () async {
        List<DefaultGiftPageController> service = [];
        // 解析礼物JSON并将解析结果填充到DefaultGiftPageController的gifts列表中。
        final value = await rootBundle.loadString('data/Gifts.json');
        Map<String, dynamic> map = json.decode(value);
        for (var element in map.keys.toList()) {
          service.add(
            DefaultGiftPageController(
              title: element,
              gifts: () {
                List<GiftEntityProtocol> list = [];
                map[element].forEach((element) {
                  // 将JSON解析为符合GiftEntityProtocol协议的对象。
                  GiftEntityProtocol? gift = ChatroomUIKitClient
                      .instance.giftService
                      .giftFromJson(element);
                  if (gift != null) {
                    list.add(gift);
                  }
                });
                return list;
              }(),
            ),
          );
        }
        return service;
      }(),
    );

礼物列表显示后，可以在ChatInputBar中添加按钮以显示礼物列表。

@override
Widget build(BuildContext context) {
  Widget content = Scaffold(
    resizeToAvoidBottomInset: false,
    appBar: AppBar(),
    body: ChatRoomUIKit(
      controller: controller,
      inputBar: ChatInputBar(
        actions: [
          InkWell(
            onTap: () => controller.showGiftSelectPages(),
            child: Padding(
              padding: const EdgeInsets.all(3),
              child: Image.asset('images/send_gift.png'),
            ),
          ),
        ],
      ),
      child: (context) {
        return Container();
      },
    ),
  );

  return content;
}

可以选择礼物并点击Send发送。

礼物可以通过以下组件之一显示：

ChatroomGiftMessageListView组件

ChatroomGiftMessageListView组件用于显示发送和接收的礼物。确保此组件是ChatRoomUIKit的子节点。可以在屏幕上添加此组件并设置其位置：

@override
Widget build(BuildContext context) {
  // 不要在消息列表中显示礼物。
  ChatRoomSettings.enableMsgListGift = false;
  Widget content = Scaffold(
    resizeToAvoidBottomInset: false,
    appBar: AppBar(),
    body: ChatRoomUIKit(
      controller: controller,
      child: (context) {
        return const Stack(
          children: [
            Positioned(
              left: 16,
              right: 180,
              height: 84,
              bottom: 300,
              child: ChatroomGiftMessageListView(),
            ),
            ...
          ],
        );
      },
    ),
  );

  return content;
}

ChatroomGiftMessageListView允许设置礼物小部件和占位符图标。

const ChatroomGiftMessageListView({
  this.giftWidgetBuilder,
  this.placeholder,
  super.key,
});

ChatroomGlobalBroadcastView组件

ChatroomGlobalBroadcastView组件用于显示全局广播消息。请记住将其设置为ChatRoomUIKit的子节点。可以在屏幕上添加ChatroomGlobalBroadcastView组件并设置其位置：

@override
Widget build(BuildContext context) {
  Widget content = Scaffold(
    resizeToAvoidBottomInset: false,
    appBar: AppBar(),
    body: ChatRoomUIKit(
      controller: controller,
      child: (context) {
        return Stack(
            children: [
              Positioned(
                top: MediaQuery.of(context).viewInsets.top + 10,
                height: 20,
                left: 20,
                right: 20,
                child: const ChatroomGlobalBroadcastView(),
              ),
              ...
            ],
          );
      },
    ),
  );

  return content;
}

ChatroomGlobalBroadcastView允许设置图标、字体和背景颜色。

const ChatroomGlobalBroadcastView({
  this.icon,
  this.textStyle,
  this.backgroundColor,
  super.key,
});

ChatRoomSettings类

ChatRoomSettings类提供ChatroomUIKit的设置。

class ChatRoomSettings {
  static String? userDefaultAvatar; // 默认头像。
  static String? defaultIdentify; // 默认身份图标。
  static String? defaultGiftIcon; // 默认礼物图标。

  static bool enableMsgListTime = true; // 消息列表是否显示时间。
  static bool enableMsgListAvatar = true; // 消息列表是否显示头像。
  static bool enableMsgListNickname = true; // 消息列表是否显示昵称。
  static bool enableMsgListIdentify = true; // 消息列表是否显示身份。

  static bool enableMsgListGift = false; // 消息列表是否显示礼物。

  static bool enableParticipantItemIdentify = false; // 参与者列表是否显示身份。

  static CornerRadius inputBarRadius = CornerRadius.large; // 输入框的圆角半径。
  static CornerRadius avatarRadius = CornerRadius.large; // 头像的圆角半径。
}

更多关于Flutter聊天室UI组件插件chatroom_uikit的使用的实战教程也可以访问 https://www.itying.com/category-92-b0.html

1 回复

更多关于Flutter聊天室UI组件插件chatroom_uikit的使用的实战系列教程也可以访问 https://www.itying.com/category-92-b0.html


chatroom_uikit 是一个用于快速构建聊天室界面的 Flutter UI 组件库。它提供了丰富的组件和功能，帮助你快速实现聊天室应用。以下是如何使用 chatroom_uikit 的基本步骤和示例代码。

1. 添加依赖

首先，你需要在 pubspec.yaml 文件中添加 chatroom_uikit 依赖：

dependencies:
  flutter:
    sdk: flutter
  chatroom_uikit: ^1.0.0  # 请使用最新版本

然后运行 flutter pub get 来安装依赖。

2. 基本用法

2.1 初始化聊天室

在使用 chatroom_uikit 之前，你需要初始化聊天室。通常，你需要提供一些必要的配置，如用户信息、聊天室 ID 等。

import 'package:chatroom_uikit/chatroom_uikit.dart';

void main() {
  ChatRoomKit.initialize(
    appKey: 'YOUR_APP_KEY',
    userId: 'YOUR_USER_ID',
    userToken: 'YOUR_USER_TOKEN',
  );
  runApp(MyApp());
}

2.2 创建聊天室页面

使用 ChatRoomPage 组件来创建一个聊天室界面。

import 'package:flutter/material.dart';
import 'package:chatroom_uikit/chatroom_uikit.dart';

class ChatRoomScreen extends StatelessWidget {
  final String roomId;

  ChatRoomScreen({required this.roomId});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('Chat Room'),
      ),
      body: ChatRoomPage(
        roomId: roomId,
        onMessageSent: (message) {
          // 处理消息发送事件
          print('Message sent: $message');
        },
        onMessageReceived: (message) {
          // 处理消息接收事件
          print('Message received: $message');
        },
      ),
    );
  }
}

2.3 处理消息事件

ChatRoomPage 提供了 onMessageSent 和 onMessageReceived 回调，分别用于处理消息发送和接收事件。

ChatRoomPage(
  roomId: roomId,
  onMessageSent: (message) {
    // 处理消息发送事件
    print('Message sent: $message');
  },
  onMessageReceived: (message) {
    // 处理消息接收事件
    print('Message received: $message');
  },
),

2.4 自定义 UI

chatroom_uikit 允许你自定义聊天室的 UI。你可以通过传递自定义的 messageBuilder 来改变消息的显示方式。

ChatRoomPage(
  roomId: roomId,
  messageBuilder: (context, message) {
    return Container(
      padding: EdgeInsets.all(8.0),
      margin: EdgeInsets.symmetric(vertical: 4.0),
      decoration: BoxDecoration(
        color: Colors.blue[100],
        borderRadius: BorderRadius.circular(8.0),
      ),
      child: Text(
        message.text,
        style: TextStyle(color: Colors.black),
      ),
    );
  },
),

3. 其他功能

chatroom_uikit 还提供了其他功能，如消息撤回、消息删除、用户管理等。你可以查看官方文档以获取更多信息。

4. 示例项目

你可以查看 chatroom_uikit 的示例项目来获取更多使用示例和灵感。

git clone https://github.com/example/chatroom_uikit_example.git
cd chatroom_uikit_example
flutter run
回到顶部