属性及方法

IOpenOptions

调用 open() 方法打开直播 WebView 时，需传入此对象以配置相关参数。

| | | | | | \

配置项	类型	是否必选	默认值	说明
contentPlayerWebViewId	\
	string	是	无	\
				当前播放器 WebView 实例的唯一标识。您需使用唯一字符串，例如直播间 ID 或播放器实例 ID。不同播放器 WebView 实例应使用不同的值。该标识用于播放器 WebView 的创建、恢复、小窗展示和系统画中画等场景。请勿直接使用 plus.webview.currentWebview().id 作为 contentPlayerWebViewId。

IContentIdOptions

播放器 WebView 内容标识配置信息。

| | | | | | \

配置项	类型	是否必选	默认值	说明
contentPlayerWebViewId	string	否	无	播放器 WebView 逻辑唯一标识。未传时 SDK 会优先使用当前激活内容或小窗内容。
id	string	否	无	与 contentPlayerWebViewId 等价，主要用于兼容底层 native id 字段。

ICloseOptions

播放器 WebView 关闭配置信息。继承自 IContentIdOptions。

| | | | | | \

配置项	类型	是否必选	默认值	说明
contentPlayerWebViewId	string	否	无	播放器 WebView 逻辑唯一标识。未传时 SDK 会优先使用当前激活内容或小窗内容。
id	string	否	无	与 contentPlayerWebViewId 等价，主要用于兼容底层 native id 字段。
mode	`'close'	'hide'`	否	'close'
				* close：销毁 WebView。
				* hide：仅隐藏并保留 WebView，可通过 show 恢复。

IPiPSize

小窗尺寸配置。
类型

number | { ratio?: number; landscape?: number; portrait?: number; videoWidth?: number; videoHeight?: number }

• 当类型为 number 时，直接指定小窗宽度占屏幕宽度的比例。

• 当类型为对象时，支持以下字段：

  | | | | | | \

  配置项	类型	是否必选	默认值	说明
  ratio	number	否	无	小窗宽度占屏幕宽度的比例，取值 0 到 1。
  landscape	number	否	无	横屏时小窗宽度占屏幕宽度的比例，取值 0 到 1。
  portrait	number	否	无	竖屏时小窗宽度占屏幕宽度的比例，取值 0 到 1。
  videoWidth	number	否	无	视频原始宽度，用于计算小窗宽高比。
  videoHeight	number	否	无	视频原始高度，用于计算小窗宽高比。

IPiPConfig

小窗（画中画）配置信息。

| | | | | | \

配置项	类型	是否必选	默认值	说明
pipSize	IPiPSize	否	无	小窗尺寸配置。
allowedRoomStatuses	number[]	否	[1, 2, 3]	允许进入小窗或系统画中画的直播间状态列表。取值如下：
				* 1：直播中
				* 2：预告
				* 3：回放
iframeId	string	否	无	需要承接小窗的 H5 iframe id。
enablePullRefresh	boolean	否	无	是否允许下拉刷新。
enableSwipeBack	boolean	否	无	是否允许侧滑返回。iOS 会实际控制交互式侧滑返回；Android 当前主要用于配置持久化和后续扩展。
systemPiPStartDelayMs	number	否	无	系统 PiP 启动延迟，单位 ms。当前仅 iOS 生效，取值范围 0 到 2000。

IGestureConfig

手势配置信息。

| | | | | | \

配置项	类型	是否必选	默认值	说明
enablePullRefresh	boolean	否	无	是否允许下拉刷新。
enableSwipeBack	boolean	否	无	是否允许侧滑返回。

ByteLiveEvent

播放器 WebView 事件对象。

| | | | | | \

配置项	类型	是否必选	默认值	说明
name	string	是	无	事件名称。例如 onByteLiveNativeWebViewEvent、onEnterInAppPiP。
type	string	否	无	事件类型。例如 loaded、progress、navExitPlayer、nativeApiRequest。
id	string	否	无	播放器 WebView 逻辑唯一标识。
runtimeWebViewId	string	否	无	播放器 WebView 在运行时的 ID。
detail	Record<string, any>	否	无	事件详情。
raw	any	否	无	原始事件对象。

控制页面生命周期

open()

打开直播 WebView。

类型

(url: string, options: IOpenOptions) => void

参数

| | | | | | \

名称	类型	是否必选	默认值	说明
url	string	是	无	直播 WebView 地址。
options.contentPlayerWebViewId	string	是	无	播放器 WebView 逻辑唯一标识，由业务传入。SDK 会将该值映射到底层 native id，用于后续展示、隐藏、关闭和小窗控制。

close()

关闭或隐藏直播 WebView。

类型

(options?: ICloseOptions) => void

参数

| | | | | | \

名称	类型	是否必选	默认值	说明
options.contentPlayerWebViewId / options.id	string	否	当前激活内容	指定要关闭或隐藏的播放器 WebView；未传时使用当前激活内容或小窗内容。
options.mode	`'close'	'hide'`	否	'close'

show()

恢复显示已隐藏或处于应用内小窗态的直播 WebView。

类型

() => void

说明

show() 是 maximize() 的便捷方法。当前 WebView 已经处于大窗可见状态时，调用基本无副作用；如果 WebView 已通过 close 销毁，则无法恢复，需要重新调用 open()。

maximize()

以大窗模式展示直播 WebView。

类型

(options?: IContentIdOptions) => void

说明

未传 options 时，SDK 会优先使用当前激活内容或当前小窗内容。若没有可恢复内容，则不会展示新的 WebView。

控制小窗与 PiP

enterInAppPiP()

进入应用内小窗。

类型

() => boolean

返回值

返回是否成功发起进入应用内小窗。

minimize()

将直播 WebView 切换为应用内悬浮小窗模式。

类型

(options?: IContentIdOptions) => boolean

返回值

返回是否成功发起进入应用内小窗。该方法与 enterInAppPiP() 能力一致。

exitMiniWindow()

退出应用内小窗模式，返回到正常大窗播放状态。

类型

() => void

setPiPConfig()

设置 PiP 小窗整体配置。

类型

(config: IPiPConfig) => void

参数

| | | | | | \

名称	类型	是否必选	默认值	说明
config	IPiPConfig	是	无	PiP 行为配置。

setPiPSize()

设置 PiP 小窗尺寸。

类型

(size: IPiPSize) => void

参数

| | | | | | \

名称	类型	是否必选	默认值	说明
size	IPiPSize	是	无	小窗尺寸配置。传入数字时表示小窗宽度占屏幕宽度的比例；传入对象时可分别设置 ratio、landscape、portrait 或通过 videoWidth/videoHeight 指定宽高比。

setGestureConfig()

设置小窗手势能力。

类型

(config: IGestureConfig) => void

参数

| | | | | | \

名称	类型	是否必选	默认值	说明
config	IGestureConfig	是	无	手势配置。当前可配置 enablePullRefresh 和 enableSwipeBack。

notifyWebview()

向直播 H5 页面发送事件。

类型

(eventKey: number, payload?: any) => void

参数

| | | | | | \

名称	类型	是否必选	默认值	说明
eventKey	number	是	无	事件标识。该值由 H5/Web 观播 SDK 的 Native 回调协议约定，宿主需要与 H5 页面约定具体事件枚举。
payload	any	否	无	事件数据。SDK 会将该对象作为 info 字段传给 H5 页面。

WebView 请求 Native API

企业直播 H5 可通过桥接能力向宿主发起 Native API 调用请求。
Android / iOS SDK 不直接实现分享、支付、下载、路由或本地存储等能力，仅负责将 H5 请求转发至宿主，并将宿主执行结果回传至 H5。
宿主需在 ByteLiveBridgeHandler.onNativeApiRequest(request, responder) 中处理请求，并根据执行结果调用以下方法返回结果：

• responder.success()
• responder.fail()
• responder.complete()
• responder.progress()

常见请求类型如下，最终支持范围以宿主实现为准：

• share：调用宿主分享能力。
• requestPayment：发起支付请求。
• downloadFile / downloadFileAbort：下载文件或取消下载。
• saveImageToPhotosAlbum：保存图片到相册。
• route：页面路由跳转。uni-app 适配层中对应 navigateTo、redirectTo、switchTab 等方法。
• storage：本地存储读写。uni-app 适配层通过独立 storage bridge 承接 get / set / remove 等操作。

事件

宿主通过 SDK 初始化配置中的事件监听器接收事件。事件对象结构见 ByteLiveEvent，其中 name 表示事件名称，type 表示具体事件类型，id 表示播放器 WebView 逻辑唯一标识，runtimeWebViewId 表示底层 WebView 实例标识，detail 为事件详情。

WebView 内容事件

当 name 为 onByteLiveNativeWebViewEvent 时，可通过 type 判断具体事件：

| | | \

type	说明
loading	WebView 开始加载。
loaded	WebView 加载完成。
title	页面标题变化。
progress	页面加载进度变化。
error	页面加载或运行错误。
navExitPlayer	退出播放器事件，例如点击退出、宿主主动关闭 WebView 或返回上一层页面。
shellShown	宿主容器变为可见。
shellHidden	宿主容器被隐藏。
invokeNative	H5 通过 window.ByteLiveJsBridge.invokeNative() 向宿主发送消息。
nativeApiRequest	H5 通过 window.ByteLiveNativeApi.request() 发起 Native API 请求。
newWindow	H5 请求打开新窗口。

PiP 事件

PiP 相关事件通过独立 name 分发：

| | | \

name	说明
onEnterInAppPiP	已进入应用内小窗。
onExitInAppPiP	已退出应用内小窗。
onEnterSystemPiP	已进入系统 PiP。
onExitSystemPiP	已退出系统 PiP。
onEnterInAppPiPPolicyBlocked	因策略限制未进入应用内小窗。
onEnterSystemPiPFailed	进入系统 PiP 失败。
onInAppPiPMoveEnd	应用内小窗拖拽结束。
onInAppPiPClick	应用内小窗被点击。