TUILiveKit 的直播列表能力基于 LiveListView,以竖向分页信息流的形式展示多个直播间,观众上下滑动即可切换,可快速集成到您的 Flutter 应用中。集成提示:
功能概览
直播间信息流:以竖向分页容器展示多个直播间,每一页都是完整的观看界面。
上下滑动切换:观众上下滑动即可切换到上一个 / 下一个直播间,播放与进房状态由组件自动管理。
首屏置顶:构造时传入的 liveID 会被置顶到列表第一位,保证从分享链接、推送通知进入时首屏看到的就是目标直播间。
分页加载:滑动到列表末尾前自动回调
onLoadMore,可对接 LiveListStore 或您自己的业务服务端追加下一页数据。直播间切换 | 直播观看 |
![]() |
![]() |
组件说明
LiveListView 是一个 StatelessWidget,统一从 package:tencent_live_uikit/tencent_live_uikit.dart 导入,作为竖向分页的直播间信息流容器;每一页内部都由 PlayerView 承载,因此单个直播间的播放能力(拉流、进房、连麦、弹幕、礼物、点赞)与 观众观看 文档完全一致。组件采用「Widget + Controller」结构:
LiveListViewController 负责注入列表数据;在控制器尚未挂载时调用 setData / appendData,数据会被缓存,组件挂载后自动生效。说明:
宿主 App 需声明摄像头与麦克风权限;iOS 端还需在 Podfile 中打开
PERMISSION_CAMERA=1、PERMISSION_MICROPHONE=1,否则连麦时权限请求会直接失败。快速接入
步骤1:开通服务
步骤2:代码集成
注意:
创建 LiveListView 之前,请确保已完成登录,否则拉流与进房会失败。
步骤3:接入 LiveListView 滑动切换直播间
在您的直播列表观看页中创建
LiveListView,并通过 LiveListViewController 注入直播间列表数据:import 'package:atomic_x_core/atomicxcore.dart';import 'package:flutter/material.dart';import 'package:tencent_live_uikit/tencent_live_uikit.dart';class AudienceLiveListPage extends StatefulWidget {const AudienceLiveListPage({super.key, this.liveID = ''});final String liveID;@overrideState<AudienceLiveListPage> createState() => _AudienceLiveListPageState();}class _AudienceLiveListPageState extends State<AudienceLiveListPage> {static const int pageSize = 6;final LiveListViewController liveListController = LiveListViewController();final LiveListStore liveListStore = LiveListStore.shared;bool isLoading = false;int lastAppliedCount = 0;@overridevoid initState() {super.initState();// 1. 拉取首屏直播间列表refresh();}Future<void> refresh() async {if (isLoading) return;isLoading = true;final CompletionHandler handler =await liveListStore.fetchLiveList(cursor: '', count: pageSize);isLoading = false;if (!handler.isSuccess) {debugPrint('fetchLiveList failed: ${handler.errorCode}');return;}// 2. 全量设置列表数据final List<LiveInfo> list = liveListStore.liveState.liveList.value;lastAppliedCount = list.length;liveListController.setData(list);}Future<void> loadMore() async {if (isLoading) return;final String cursor = liveListStore.liveState.liveListCursor.value;if (cursor.isEmpty) return;isLoading = true;final int oldCount = lastAppliedCount;final CompletionHandler handler =await liveListStore.fetchLiveList(cursor: cursor, count: pageSize);isLoading = false;if (!handler.isSuccess) {debugPrint('fetchLiveList failed: ${handler.errorCode}');return;}// 3. 只把新增的一页追加到列表尾部final List<LiveInfo> list = liveListStore.liveState.liveList.value;if (list.length > oldCount) {liveListController.appendData(list.sublist(oldCount));lastAppliedCount = list.length;}}@overrideWidget build(BuildContext context) {return Scaffold(backgroundColor: Colors.black,body: LiveListView(controller: liveListController,liveID: widget.liveID,onLoadMore: loadMore,),);}}
步骤4:跳转到直播列表页面
在您需要跳转到直播列表观看页时,可参考如下代码示例:
import 'package:flutter/material.dart';import 'audience_live_list_page.dart';void enterLiveListPage(BuildContext context, String liveID) {Navigator.of(context).push(MaterialPageRoute<void>(builder: (_) => AudienceLiveListPage(liveID: liveID),fullscreenDialog: true,),);}
组件 API 说明
LiveListView 与 LiveListViewController
LiveListView 是一个 StatelessWidget,作为竖向分页的直播间信息流容器。方法 / 属性 | 说明 |
LiveListView({controller, liveID, initialLiveID, onLoadMore}) | 构造方法。liveID 会作为首屏直播间;同时传入 initialLiveID 时以 initialLiveID 优先。 |
onLoadMore | 观众滑动到距离列表末尾还剩 2 个直播间时触发,用于加载下一页数据。 |
LiveListViewController.setData(List<LiveInfo> list) | 全量设置直播间列表数据;未挂载时数据会被缓存。 |
LiveListViewController.appendData(List<LiveInfo> list) | 在列表尾部追加直播间数据,用于分页加载。 |
LiveListViewController.isAttached | 控制器是否已挂载到 LiveListView。 |
直播间列表数据
组件自身不负责拉列表。列表来自 AtomicXCore 的 LiveListStore:
能力 | 接口 |
拉取列表 | LiveListStore.shared.fetchLiveList(cursor: String, count: int),返回 Future<CompletionHandler> |
列表数据 | LiveListStore.shared.liveState.liveList.value |
分页游标 | LiveListStore.shared.liveState.liveListCursor.value(为空表示没有更多数据) |
下一步
恭喜您,现在您已经成功集成了直播列表。接下来,您可以实现观众观看、主播开播、礼物系统等功能,可参考下表:
常见问题
LiveListView 设置了数据但列表为空?
请确认已把
LiveListViewController 同时传给 LiveListView(controller: ...),并调用 setData 注入数据;LiveListView 本身不会拉取列表。数据也可来自您自己的业务服务端。首屏没有展示指定的直播间?
请确认已把 liveID 传给 LiveListView(或使用 initialLiveID),并在拉取首屏数据后调用 setData;组件会把该 liveID 置顶到列表第一位。
观众连麦时还能上下滑动切换直播间吗?
不能。观众进入 coGuest 状态后组件会自动禁用滑动切换,避免误触导致连麦中断;连麦结束后恢复。

