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

观众观看(HarmonyOS)

最近更新时间:2026-11-11 16:15:31
我的收藏
TUILiveKit 的观众观看页为用户提供了丰富且便捷的直播观看与互动功能,能快速集成到您的应用中,满足观众多样化的需求。

功能概览

直播预览:未进房前即可先预览主播实时画面,点击进入直播间后再参与互动。
直播观看:清晰、流畅观看主播实时直播画面,可查看直播间标题、主播信息及在线观众。
直播互动:送礼物(有动画特效,主播接收提示)、点赞(有动画及实时统计)、发弹幕互动,并可申请与主播音视频连麦互动。
直播预览
直播观看
直播互动






组件说明

PlayerView 是 ArkUI 组件,用于观看单个直播间,统一从 tuilivekit 导入;它通过 PlayerViewController 暴露播放控制。组件内已包含拉流、进房、连麦、弹幕、礼物、点赞等完整交互 UI。

快速接入

步骤 1. 开通服务

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

步骤 2. 代码集成

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

步骤 3. 使用 PlayerView 观看单个直播间

在您的观众观看页中创建 PlayerView 并持有 PlayerViewController:
ArkTS
import { LiveInfo } from '@tencentcloud/atomicxcore'
import { PlayerStatus, PlayerView, PlayerViewController } from 'tuilivekit'

@Entry
@Component
struct AudiencePlayerPage {
liveID: string = ''
onBack?: () => void
private controller: PlayerViewController = new PlayerViewController()
private unsubscribeStatus?: () => void

aboutToAppear(): void {
// 1. 设置直播间信息(必须在 startPlay / joinChannel 之前调用)
const liveInfo = new LiveInfo()
liveInfo.liveID = this.liveID
this.controller.setLiveInfo(liveInfo)

// 2. 监听关闭、进房事件
this.controller.onCloseClicked = () => this.onBack?.()
this.controller.onJoinLiveClicked = () => console.info(`join live: ${this.liveID}`)

// 3. (可选) 监听播放状态变化,返回值为取消订阅闭包
this.unsubscribeStatus = this.controller.status((status: PlayerStatus) => {
console.info(`player status: ${status}`)
})

// 4. 开始拉流播放
this.controller.startPlay()

// 5. 加入直播间,进房成功后观众才能发弹幕、点赞、送礼、连麦
this.controller.joinChannel().then((info: LiveInfo) => {
console.info(`joinChannel success: ${info.liveID}`)
}).catch((error: Error) => {
console.error(`joinChannel failed: ${error.message}`)
})
}

aboutToDisappear(): void {
// 6. 页面销毁时取消订阅、停止播放并退出直播间
this.unsubscribeStatus?.()
this.controller.stopPlay()
this.controller.leaveChannel()
}

build() {
PlayerView({ controller: this.controller })
}
}

步骤 4. 跳转到观众观看页面

在您的房间列表页点击直播间卡片时,可通过 NavPathStack 跳转到承载 PlayerView 的页面,并把 liveID 作为路由参数传入;路由名由您的宿主工程自行定义:
Kotlin
this.navigationStack.pushPath({ name: 'singlePlayer', param: liveID })

组件 API 说明

PlayerView

PlayerView 是 ArkUI 组件,用于观看单个直播间。
属性
说明
controller
PlayerViewController,播放控制入口。不传时组件使用自己新建的控制器。

PlayerViewController

方法 / 属性
说明
setLiveInfo(liveInfo: LiveInfo)
设置直播间信息。必须在 startPlay、joinChannel 之前调用;切换直播间时组件会先停止播放并退出原直播间。
startPlay()
开始拉流播放(仅播放画面,尚未进房)。
stopPlay()
停止拉流播放。
joinChannel(): Promise<LiveInfo>
加入直播间,成功后返回直播间信息。进房成功后观众才能发弹幕、点赞、送礼、申请连麦。
leaveChannel(): Promise<void>
退出直播间。
setVolume(volume: number)
设置播放音量,取值范围 0 ~ 100。
joinLiveEntranceEnabled
是否展示进入直播间入口。
status(listener)
订阅播放状态,返回取消订阅的闭包;订阅时会立即回调当前状态。
liveID
当前观看的直播间 ID。
onCloseClicked
观众点击关闭按钮时回调(组件会先退出直播间再回调)。
onJoinLiveClicked
观众通过进入直播间入口进房成功时回调。

PlayerStatus

PlayerViewController.status 的播放状态,取值如下:
状态
说明
idle
空闲,未播放也未进房。
playing
正在拉流播放,观众尚未进房(展示进入直播间入口)。
inRoom
已进房,观众可参与弹幕、点赞、送礼、连麦等互动。
coGuest
连麦中(申请中或已上麦)。
end
直播已结束或被踢出,组件展示直播结束页。

下一步

恭喜您,现在您已经成功集成了观众观看。接下来,您可以实现主播开播、直播列表等功能,可参考下表:
功能
描述
集成指引
主播开播
主播开播全流程功能,包括开播前的准备和开播后的各种互动。
直播列表
以信息流形式展示多个直播间,支持上下滑动切换与分页加载。

常见问题

调用了 startPlay 或 joinChannel 后没有画面 / 进房失败?

请先确认:
已调用 setLiveInfo() 设置直播间信息,且 LiveInfo.liveID 不为空;
已完成 AtomicXCore 登录;
该直播间确实处于开播状态;
宿主 module.json5 已声明网络权限。

观众选择视频连麦后,视频画面显示黑屏?

请检查宿主 module.json5 中 ohos.permission.CAMERA、ohos.permission.MICROPHONE 的 requestPermissions 声明,以及用户是否已授权;组件内的开播页会在运行时动态申请权限,观众侧权限仍需在宿主模块中声明。

观众发送弹幕时,直播间内其他观众看不到弹幕内容?

原因 1:先检查网络连接,确保观众设备网络正常。
原因 2:该观众被主播禁言,无法发送弹幕。
原因 3:观众的弹幕内容涉及关键词屏蔽,请确认观众发送的弹幕内容是否符合直播间规则。