TUILiveKit 的直播列表能力基于 LiveListView,以竖向分页信息流的形式展示多个直播间,观众上下滑动即可切换,可快速集成到您的 HarmonyOS 应用中。功能概览
直播间信息流:以竖向分页容器展示多个直播间,每一页都是完整的观看界面。
上下滑动切换:观众上下滑动即可切换到上一个 / 下一个直播间,播放与进房状态由组件自动管理。
首屏置顶:构造时传入的 liveID 会被置顶到列表第一位,保证从分享链接、推送通知进入时首屏看到的就是目标直播间。
分页加载:滑动到列表末尾前自动回调 onLoadMore,可对接 LiveListStore 或您自己的业务服务端追加下一页数据。
直播间切换 | 直播观看 |
![]() |
![]() |
组件说明
LiveListView 是 ArkUI @Component struct,统一从 'tuilivekit' 导入,作为竖向分页的直播间信息流容器;每一页内部都由 PlayerView 承载,因此单个直播间的播放能力(拉流、进房、连麦、弹幕、礼物、点赞)与 观众观看 文档完全一致。说明:
HarmonyOS 端的 LiveListView 没有
setData / appendData 方法:列表数据通过 @Prop liveList 由宿主的 @State 状态驱动注入,状态变化时组件自动刷新并按 liveID 合并去重。快速接入
步骤1:开通服务
步骤2:代码集成
注意:
创建 LiveListView 之前,请确保已完成登录,否则拉流与进房会失败。
宿主模块需在
module.json5 中声明 ohos.permission.INTERNET、ohos.permission.GET_NETWORK_INFO、ohos.permission.CAMERA、ohos.permission.MICROPHONE。组件 HAR 自身不声明这些权限。步骤3:接入 LiveListView 滑动切换直播间
在您的直播列表观看页中创建
LiveListView,并把 @State 状态中的直播间列表传给组件:import { LiveInfo, LiveListStore } from '@tencentcloud/atomicxcore'import { LiveListView } from 'tuilivekit'@Entry@Componentstruct AudienceLiveListPage {liveID: string = ''@State private liveList: LiveInfo[] = []private readonly liveListStore: LiveListStore = LiveListStore.shared()private readonly pageSize: number = 6private isLoading: boolean = falseaboutToAppear(): void {// 1. 拉取首屏直播间列表(cursor 为空表示从头开始)this.fetch('')}private fetch(cursor: string): void {if (this.isLoading) {return}this.isLoading = truethis.liveListStore.fetchLiveList(cursor, this.pageSize).then(() => {this.isLoading = false// 2. 从 LiveListStore 读取最新列表,更新 @State 驱动组件刷新this.liveList = this.liveListStore.liveState.liveList.getAllData()}).catch((error: Error) => {this.isLoading = falseconsole.error(`fetchLiveList failed: ${error.message}`)})}private loadMore(): void {const cursor = this.liveListStore.liveState.liveListCursorif (cursor.length === 0) {return}this.fetch(cursor)}build() {LiveListView({ liveID: this.liveID, liveList: this.liveList, onLoadMore: () => this.loadMore() })}}
步骤4:跳转到直播列表页面
在直播列表页点击直播间卡片时,可通过
NavPathStack 跳转到滑动切换观看页;在 Navigation 的 navDestination 构造器中按路由名创建对应页面:@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(为空表示没有更多数据) |
下一步
恭喜您,现在您已经成功集成了直播列表。接下来,您可以实现观众观看、主播开播、礼物系统等功能,可参考下表:
常见问题
LiveListView 传入了数据但列表为空?
请确认传入的是宿主的
@State 变量(例如 LiveListView({ liveID, liveList: this.liveList, onLoadMore })),并且在列表拉取成功后真正更新了该变量。HarmonyOS 端没有 setData / appendData 方法,组件不会自行拉取数据。首屏没有展示指定的直播间?
请确认已把
liveID 传给 LiveListView,并在拉取首屏数据后更新 @State liveList;组件会把该 liveID 置顶到列表第一位。观众连麦时还能上下滑动切换直播间吗?
不能。观众进入
coGuest 状态后组件会自动禁用滑动切换,避免误触导致连麦中断;连麦结束后恢复。
