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

直播列表(HarmonyOS)

最近更新时间:2026-11-11 16:15:31
本文档已由 AI 辅助审校
我的收藏
TUILiveKit 的直播列表能力基于 LiveListView,以竖向分页信息流的形式展示多个直播间,观众上下滑动即可切换,可快速集成到您的 HarmonyOS 应用中。

功能概览

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




组件说明

LiveListView 是 ArkUI @Component struct,统一从 'tuilivekit' 导入,作为竖向分页的直播间信息流容器;每一页内部都由 PlayerView 承载,因此单个直播间的播放能力(拉流、进房、连麦、弹幕、礼物、点赞)与 观众观看 文档完全一致。
说明:
HarmonyOS 端的 LiveListView 没有 setData / appendData 方法:列表数据通过 @Prop liveList 由宿主的 @State 状态驱动注入,状态变化时组件自动刷新并按 liveID 合并去重。

快速接入

步骤1:开通服务

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

步骤2:代码集成

参考 准备工作 接入 TUILiveKit ,并完成 AtomicXCore 登录。
注意:
创建 LiveListView 之前,请确保已完成登录,否则拉流与进房会失败。
宿主模块需在 module.json5 中声明 ohos.permission.INTERNET、ohos.permission.GET_NETWORK_INFO、ohos.permission.CAMERA、ohos.permission.MICROPHONE。组件 HAR 自身不声明这些权限。

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

在您的直播列表观看页中创建 LiveListView,并把 @State 状态中的直播间列表传给组件:
ArkTS

import { LiveInfo, LiveListStore } from '@tencentcloud/atomicxcore'
import { LiveListView } from 'tuilivekit'

@Entry
@Component
struct AudienceLiveListPage {
liveID: string = ''
@State private liveList: LiveInfo[] = []
private readonly liveListStore: LiveListStore = LiveListStore.shared()
private readonly pageSize: number = 6
private isLoading: boolean = false

aboutToAppear(): void {
// 1. 拉取首屏直播间列表(cursor 为空表示从头开始)
this.fetch('')
}

private fetch(cursor: string): void {
if (this.isLoading) {
return
}
this.isLoading = true
this.liveListStore.fetchLiveList(cursor, this.pageSize).then(() => {
this.isLoading = false
// 2. 从 LiveListStore 读取最新列表,更新 @State 驱动组件刷新
this.liveList = this.liveListStore.liveState.liveList.getAllData()
}).catch((error: Error) => {
this.isLoading = false
console.error(`fetchLiveList failed: ${error.message}`)
})
}

private loadMore(): void {
const cursor = this.liveListStore.liveState.liveListCursor
if (cursor.length === 0) {
return
}
this.fetch(cursor)
}

build() {
LiveListView({ liveID: this.liveID, liveList: this.liveList, onLoadMore: () => this.loadMore() })
}
}

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

在直播列表页点击直播间卡片时,可通过 NavPathStack 跳转到滑动切换观看页;在 Navigation 的 navDestination 构造器中按路由名创建对应页面:
Kotlin
@Provide('navigationStack') private navigationStack: NavPathStack = new NavPathStack()

Navigation(this.navigationStack) {
WaterfallViewController({
onPlay: (liveID: string) => this.navigationStack.pushPath({ name: 'player', param: liveID }),
})
}
.mode(NavigationMode.Stack)
.navDestination(this.navigationDestination)

组件 API 说明

LiveListView

LiveListView 是 ArkUI 组件,作为竖向分页的直播间信息流容器。
属性
说明
liveID: string
首屏直播间 ID;不传则展示列表第一条。
@Prop liveList: LiveInfo[]
直播间列表数据,由宿主的 @State 状态驱动;数据变化时组件自动刷新。
onLoadMore?: () => void
观众滑动到距离列表末尾还剩 2 个直播间时触发,用于加载下一页数据。

直播间列表数据

组件自身不负责拉列表。列表来自 @tencentcloud/atomicxcore 的 LiveListStore:
能力
接口
拉取列表
LiveListStore.shared().fetchLiveList(cursor, count),返回 Promise<void>
列表数据
LiveListStore.shared().liveState.liveList.getAllData()
分页游标
LiveListStore.shared().liveState.liveListCursor(为空表示没有更多数据)

下一步

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

常见问题

LiveListView 传入了数据但列表为空?

请确认传入的是宿主的 @State 变量(例如 LiveListView({ liveID, liveList: this.liveList, onLoadMore })),并且在列表拉取成功后真正更新了该变量。HarmonyOS 端没有 setData / appendData 方法,组件不会自行拉取数据。

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

请确认已把 liveID 传给 LiveListView,并在拉取首屏数据后更新 @State liveList;组件会把该 liveID 置顶到列表第一位。

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

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