文档概览/
Feedback

语聊组件（Flutter）

组件概述

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

准备工作

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

设置麦位列表布局

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

效果预览

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

















接口说明

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

代码示例

您可以通过以下方式快速设置麦位列表布局。
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 即可。