tencent cloud

实时音视频

语聊组件(Flutter)

下载
聚焦模式
字号
最后更新时间: 2026-06-12 10:58:56

组件概述

语聊麦位组件SeatGridWidget)是专门为语音聊天室场景设计的核心 UI 控件。它自动关联麦位状态,支持展示用户信息、音量波纹及房主标识。通过本文档,您可以根据业务需求(例如多人交友、游戏开黑)快速调整麦位布局或完全自定义麦位视图。

准备工作

在开始调整语聊麦位组件前,请先参考 主播开播观众观看 完成主流程的搭建。

设置麦位列表布局

组件内置了多种布局模式,适用于不同的语聊场景。您可以通过 SeatGridControllersetLayoutMode 接口快速切换,无需手动计算位置。

效果预览

宫格布局
元素布局
纵向布局
自定义布局

















接口说明

Dart
void setLayoutMode(LayoutMode layoutMode, SeatWidgetLayoutConfig? layoutConfig)
参数
描述
layoutMode
布局模式:
LayoutMode.grid(宫格布局):适用于多人语聊场景,所有麦位均匀分布。
LayoutMode.focus(元素布局):适用于有主麦位的场景,突出显示主麦位。
LayoutMode.vertical(纵向布局):适用于竖屏场景,麦位垂直排列。
LayoutMode.free(自定义布局):适用于需要完全自定义布局的场景 。
layoutConfig
自定义的行列布局信息,仅当 layoutModeFREE 时需传入此参数。

代码示例

您可以通过以下方式快速设置麦位列表布局。
Dart
SeatGridController seatGridController = SeatGridController(liveID: 'your live id');

// 设置宫格布局
seatGridController.setLayoutMode(LayoutMode.grid);

// 设置元素布局
seatGridController.setLayoutMode(LayoutMode.focus);

// 设置纵向布局
seatGridController.setLayoutMode(LayoutMode.vertical);

// 设置自定义布局
// 第一行配置
final rowConfig1 = SeatWidgetLayoutRowConfig(
count: 3, // 第一行显示的数量
seatSpacing: 10, // 第一行每个麦位的水平间距
seatSize: Size(50, 50), // 第一行显示的每个麦位视图大小
alignment: SeatWidgetLayoutRowAlignment.center); // 第一行麦位的对齐方式

// 第二行配置
final rowConfig2 = SeatWidgetLayoutRowConfig(
count: 3, // 第二行显示的数量
seatSpacing: 10, // 第二行每个麦位的水平间距
seatSize: Size(50, 50), // 第二行显示的每个麦位视图大小
alignment: SeatWidgetLayoutRowAlignment.spaceAround); // 第二行麦位的对齐方式

final layoutConfig = SeatWidgetLayoutConfig(rowConfigs: [rowConfig1, rowConfig2], rowSpacing: 10);

seatGridController.setLayoutMode(LayoutMode.free, layoutConfig: layoutConfig);
自定义布局对齐方式示意图:


自定义麦位视图 UI

如果默认的麦位样式无法满足业务需求,您可以通过设置构建器( SeatWidgetBuilder )来完全托管麦位的渲染逻辑。

效果预览

默认麦位视图
自定义麦位视图示例







接口说明

Dart
SeatGridController seatGridController = SeatGridController(liveID: 'your live id');
SeatGridWidget(
controller: seatGridController,
seatWidgetBuilder:
(BuildContext context, ValueNotifier<SeatInfo> seatInfoNotifier, ValueNotifier<int> volumeNotifier) {
return SizedBox(); // 替换成自己的自定义麦位视图
},
);
参数
描述
seatInfoNotifer
当前麦位信息状态通知器。
volumeNotifier
当前麦上用户音量状态通知器。

代码示例

如果默认的 UI 不满足需求,您可以自定义麦位 UI ,可参考如下方式快速设置麦位布局。
Dart
SeatGridController seatGridController = SeatGridController(liveID: 'your live id');

SeatGridWidget(
controller: seatGridController,
seatWidgetBuilder:
(BuildContext context, ValueNotifier<SeatInfo> seatInfoNotifier, ValueNotifier<int> volumeNotifier) {
return TestSeatInfoWidget(seatInfo: seatInfoNotifier.value, volume: volumeNotifier.value);
},
);

seatGridView.setSeatViewDelegate(TestSeatViewDelegate())


class TestSeatInfoWidget extends StatelessWidget {
final SeatInfo seatInfo;
final int volume;

const TestSeatInfoWidget({super.key, required this.seatInfo, required this.volume});

@override
Widget build(BuildContext context) {
return Column(
children: [Text('userId:${seatInfo.userInfo.userID}'), Text('volume:$volume')],
);
}
}

常见问题

自定义适配器后,如何获取麦位点击事件?

您需要在自定义 Widget 内部设置点击监听,在回调中处理业务逻辑。

切换布局后麦位数据会丢失吗?

不会。SeatGridWidget 内部维护了数据状态,setLayoutMode 仅改变视觉排布,不会影响用户的上麦状态。

如何监听麦位列表的实时变化(如用户上麦/下麦)?

您无需在适配器中主动监听。SeatGridWidget 内部已实现了麦位注册监听,当任何麦位状态变化时,会自动触发 seatWidgetBuilder 回调方法。您只需在该方法中更新 UI 即可。


帮助和支持

本页内容是否解决了您的问题?

填写满意度调查问卷,共创更好文档体验。

文档反馈