帮你快速理解、总结文档立即下载

直播列表(Flutter)

最近更新时间:2026-11-11 16:15:31
本文档已由 AI 辅助审校
我的收藏
TUILiveKit 的直播列表能力基于 LiveListView,以竖向分页信息流的形式展示多个直播间,观众上下滑动即可切换,可快速集成到您的 Flutter 应用中。
集成提示:
本文档介绍基于 UI 组件 的观众观看方式(含完整交互 UI)。若您需通过 Core SDK 自行搭建观众端界面,请参考 观众观看 (Core SDK)。

功能概览

直播间信息流:以竖向分页容器展示多个直播间,每一页都是完整的观看界面。
上下滑动切换:观众上下滑动即可切换到上一个 / 下一个直播间,播放与进房状态由组件自动管理。
首屏置顶:构造时传入的 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:代码集成

参考 准备工作 接入 TUILiveKit。
注意:
创建 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;

@override
State<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;

@override
void 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;
}
}

@override
Widget 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(为空表示没有更多数据)

下一步

恭喜您,现在您已经成功集成了直播列表。接下来,您可以实现观众观看、主播开播、礼物系统等功能,可参考下表:
功能
描述
集成指引
观众观看
使用 PlayerView 观看单个直播间,包含拉流、进房与互动能力。
主播开播
主播开播全流程功能,包括开播前的准备和开播后的各种互动。
礼物系统
实现自定义礼物素材配置、计费系统对接、PK 场景互动等功能。

常见问题

LiveListView 设置了数据但列表为空?

请确认已把 LiveListViewController 同时传给 LiveListView(controller: ...),并调用 setData 注入数据;LiveListView 本身不会拉取列表。数据也可来自您自己的业务服务端。

首屏没有展示指定的直播间?

请确认已把 liveID 传给 LiveListView(或使用 initialLiveID),并在拉取首屏数据后调用 setData;组件会把该 liveID 置顶到列表第一位。

观众连麦时还能上下滑动切换直播间吗?

不能。观众进入 coGuest 状态后组件会自动禁用滑动切换,避免误触导致连麦中断;连麦结束后恢复。