Live Stream List (HarmonyOS)
TUILiveKit’s Live Stream List feature is powered by LiveListView, which displays multiple live rooms in a vertically paginated feed. Audiences can easily swipe up or down to switch between rooms, making integration straightforward for your application.
Feature Overview
Live Room Feed: Shows multiple live rooms in a vertically paginated container. Each page provides a complete viewing interface.
Swipe Up/Down to Switch: Audiences can swipe up or down to move to the previous or next live room. Playback and Enter Room states are automatically handled by the component.
First Screen Pinning: The liveID provided during initialization is pinned to the top of the list. When entering from a shared link or push notification, the target live room appears on the first screen.
Paginated Loading: Before reaching the end of the list, onLoadMore is triggered automatically. Connect to LiveListStore or your backend service to append the next page of data.
Live Room Switching | Live Viewing |
|
|
Component Description
LiveListView is an ArkUI @Component struct imported from 'tuilivekit', functioning as a vertically paginated live stream feed container. Each page is rendered by PlayerView, so playback features for a single live room (stream pulling, Enter Room, audience co-hosting, live comments, gifts, likes) are fully consistent with the Audience Viewing documentation.
Note:
LiveListView uses ViewPager2 and FragmentStateAdapter internally. The Activity hosting LiveListView must inherit from FragmentActivity (recommended: AppCompatActivity). Otherwise, a type cast exception will occur during construction.
Quick Integration
Step 1. Activate the Service
Refer to the Activate Service document to get the
TUILiveKit trial version or activate the paid version.Step 2. Integrate the SDK
Step 3. Integrate LiveListView for Swipe Switching Between Live Rooms
Add LiveListView to your live stream list viewing page and pass the live room list from your @State to the component:
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. Fetch the initial live room list (cursor empty means start from the beginning)this.fetch('')}private fetch(cursor: string): void {if (this.isLoading) {return}this.isLoading = truethis.liveListStore.fetchLiveList(cursor, this.pageSize).then(() => {this.isLoading = false// 2. Read the latest list from LiveListStore and update @State to trigger component refreshthis.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() })}}
Step 4. Navigate to the Live Stream List Page
When a user clicks a live room card on the live stream list page, use NavPathStack to navigate to the swipe-enabled viewing page. In the Navigation's navDestination constructor, create the corresponding page by route name:
@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 Reference
LiveListView
LiveListView is an ArkUI component that serves as a vertically paginated live stream feed container.
Property | Description |
liveID: string | Initial live room ID. If not provided, the first item in the list is displayed. |
@Prop liveList: LiveInfo[] | Live room list data, driven by the host's @State. The component automatically refreshes when the data changes. |
onLoadMore?: () => void | Triggered when the audience swipes to within 2 live rooms of the end of the list. Use this callback to load the next page of data. |
Live Stream List Data
The component does not fetch the list itself. The list is provided by LiveListStore in @tencentcloud/atomicxcore:
Capability | API |
Fetch List | LiveListStore.shared().fetchLiveList(cursor, count), returns Promise |
List Data | LiveListStore.shared().liveState.liveList.getAllData() |
Paging Cursor | LiveListStore.shared().liveState.liveListCursor (empty means no more data) |
Next Steps
You have successfully integrated the live stream list. Next, you can implement audience viewing, host broadcasting, gift system, and other features. See the table below:
Feature | Description | Integration Guide |
Audience Viewing | Use PlayerView to watch a single live room, including stream pulling, Enter Room, and interactive features. | |
Host Broadcasting | Complete workflow for host broadcasting, including pre-broadcast preparation and various interactions after going live. |
FAQs
LiveListView received data but the list is empty?
Make sure you are passing the host's @State variable (for example, LiveListView({ liveID, liveList: this.liveList, onLoadMore })), and that this variable is updated after successfully fetching the list. HarmonyOS does not have setData or appendData methods, and the component does not fetch data on its own.
The initial screen does not display the specified live room?
Ensure you have passed liveID to LiveListView and updated @State liveList after fetching the initial data. The component will pin the specified liveID to the top of the list.
Can the audience swipe up/down to switch live rooms while co-hosting?
No. When the audience enters the coGuest state, the component automatically disables swipe switching to prevent accidental interruptions of co-hosting. Swipe switching is restored after co-hosting ends.
