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

直播列表(Android)

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

功能概览

直播间信息流:以竖向分页容器展示多个直播间,每一页都是完整的观看界面。
上下滑动切换:观众上下滑动即可切换到上一个 / 下一个直播间,播放与进房状态由组件自动管理。
首屏置顶:构造时传入的 liveID 会被置顶到列表第一位,保证从分享链接、推送通知进入时首屏看到的就是目标直播间。
分页加载:滑动到列表末尾前自动回调 onLoadMore,可对接 LiveListStore 或您自己的业务服务端追加下一页数据。
直播间切换
直播观看




组件说明

LiveListView 是一个竖向分页的直播间信息流容器,内部基于 ViewPager2 + FragmentStateAdapter 实现;每一页内部都由 PlayerView 承载,因此单个直播间的播放能力(拉流、进房、连麦、弹幕、礼物、点赞)与 观众观看 文档完全一致。
说明:
LiveListView 内部使用 ViewPager2 + FragmentStateAdapter,因此承载它的 Activity 必须继承自 FragmentActivity(推荐 AppCompatActivity),否则会在构造时抛出类型强转异常。

快速接入

步骤1:开通服务

参考 开通服务 文档开通体验版或大规模直播版套餐。

步骤2:代码集成

参考 准备工作 接入 TUILiveKit ,并完成 AtomicXCore 登录。
注意:
创建 LiveListView 之前,请确保已完成登录,否则拉流与进房会失败。

步骤3:接入 LiveListView 滑动切换直播间

在您的直播列表观看页 Activity 中创建 LiveListView,并为其注入直播间列表数据:
Kotlin

import android.os.Bundle
import android.util.Log
import androidx.appcompat.app.AppCompatActivity
import com.trtc.uikit.livekit.livelist.LiveListView
import io.trtc.tuikit.atomicxcore.api.CompletionHandler
import io.trtc.tuikit.atomicxcore.api.live.LiveListStore

class AudienceLiveListActivity : AppCompatActivity() {

companion object {
private const val TAG = "AudienceLiveListActivity"
private const val FETCH_COUNT = 6
const val EXTRA_LIVE_ID = "liveID"
}

private lateinit var liveListView: LiveListView

private var isLoading = false

override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
val liveID = intent.getStringExtra(EXTRA_LIVE_ID).orEmpty()

// 1. 创建 LiveListView,构造时传入的 liveID 会作为首屏直播间
// 重写 onLoadMore,在观众滑动到列表末尾前加载更多数据
liveListView = object : LiveListView(this, liveID = liveID) {
override fun onLoadMore() {
loadMore()
}
}

// 2. 将 LiveListView 添加到界面
setContentView(liveListView)

// 3. 拉取首屏直播间列表并设置给 LiveListView
refresh()
}

private fun refresh() {
if (isLoading) return
fetch(isRefresh = true, callback = object : CompletionHandler {
override fun onSuccess() {
liveListView.setData(LiveListStore.shared().liveState.liveList.value)
isLoading = false
}

override fun onFailure(code: Int, desc: String) {
Log.e(TAG, "refresh failed, code:$code, desc:$desc")
isLoading = false
}
})
}

private fun loadMore() {
if (isLoading) return
val cursor = LiveListStore.shared().liveState.liveListCursor.value
if (cursor.isEmpty()) return

val oldSize = LiveListStore.shared().liveState.liveList.value.size
fetch(isRefresh = false, callback = object : CompletionHandler {
override fun onSuccess() {
val newList = LiveListStore.shared().liveState.liveList.value
if (newList.size > oldSize) {
liveListView.appendData(newList.subList(oldSize, newList.size))
}
isLoading = false
}

override fun onFailure(code: Int, desc: String) {
Log.e(TAG, "loadMore failed, code:$code, desc:$desc")
isLoading = false
}
})
}

private fun fetch(isRefresh: Boolean, callback: CompletionHandler) {
isLoading = true
val cursor = LiveListStore.shared().liveState.liveListCursor.value
val fetchCursor = if (isRefresh || cursor.isEmpty()) "" else cursor
LiveListStore.shared().fetchLiveList(fetchCursor, FETCH_COUNT, object : CompletionHandler {
override fun onSuccess() {
callback.onSuccess()
}

override fun onFailure(code: Int, desc: String) {
callback.onFailure(code, desc)
}
})
}
}
说明:
LiveListView 只负责渲染,不负责拉取数据。直播间列表可以来自 AtomicXCore 的 LiveListStore,也可以来自您自己的业务服务端,最终通过 setData / appendData 注入即可。
构造时传入的 liveID 会被自动置顶到列表第一位,保证观众首屏看到的就是目标直播间。
观众滑动到距离列表末尾还剩 2 个直播间时,onLoadMore 会被回调,请在此时追加下一页数据。
LiveListView 从窗口移除时会自动停止播放并退出直播间,无需您手动调用 stopPlay / leaveChannel。
观众处于连麦中时,组件会自动禁用滑动切换,避免误触导致连麦中断。

步骤4:跳转到直播列表页面

在您需要跳转到直播列表观看页时,可参考如下代码示例:
Kotlin

// 跳转到「滑动切换直播间」观看页
fun enterLiveListPage(context: Context, liveID: String) {
val intent = Intent(context, AudienceLiveListActivity::class.java)
intent.putExtra(AudienceLiveListActivity.EXTRA_LIVE_ID, liveID)
context.startActivity(intent)
}

组件 API 说明

LiveListView

LiveListView 继承自 FrameLayout,是一个竖向分页的直播间信息流容器。
方法 / 属性
说明
LiveListView(context, liveID)
构造方法。liveID 会作为首屏直播间(置顶到列表第一位);不传则展示列表第一条。
setData(liveList: List<LiveInfo>)
设置直播间列表数据。内部会自动按 liveID 去重,并将构造传入的 liveID 置顶。
appendData(liveList: List<LiveInfo>)
在列表尾部追加直播间数据,用于分页加载。已存在的直播间会被更新而非重复插入。
onLoadMore()
可重写的方法,观众滑动到距离列表末尾还剩 2 个直播间时回调,用于加载下一页数据。

直播间列表数据

组件自身不负责拉列表。列表来自 AtomicXCore 的 LiveListStore:
能力
接口
拉取列表
LiveListStore.shared().fetchLiveList(cursor, count, CompletionHandler)
列表数据
LiveListStore.shared().liveState.liveList.value
分页游标
LiveListStore.shared().liveState.liveListCursor.value(为空表示没有更多数据)

下一步

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

常见问题

创建 LiveListView 时崩溃,提示 ClassCastException?

LiveListView 内部使用 ViewPager2 + FragmentStateAdapter,需要 FragmentActivity 环境。请将承载 LiveListView 的 Activity 改为继承 AppCompatActivity(或 FragmentActivity)。
调用了 setData 后列表仍然为空?
请先确认:
已调用 setData() 注入数据,且列表中的 liveID 不为空;
已完成 AtomicXCore 登录,fetchLiveList 回调为 onSuccess;
列表数据来自您自己的业务服务端时,已转换为 LiveInfo 对象。
LiveListView 本身不会拉取列表。

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

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