文档中心

企业直播

WebView SDK

WebView SDK API 参考

属性及方法

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 会优先使用当前激活内容或小窗内容。

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'`	`close` 会关闭并销毁 WebView；`hide` 仅隐藏 WebView，后续可通过 `show()` 或 `maximize()` 恢复。传入其他值会按 `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`	应用内小窗被点击。

最近更新时间：2026.07.20 14:07:09

这个页面对您有帮助吗？

有用

无用

企业直播

IOpenOptions #

IContentIdOptions #

ICloseOptions #

IPiPSize #

IPiPConfig #

IGestureConfig #

ByteLiveEvent #

控制页面生命周期 #

open() #

类型

参数

close() #

类型

参数

show() #

类型

说明

maximize() #

类型

说明

控制小窗与 PiP #

enterInAppPiP() #

类型

返回值

minimize() #

类型

返回值

exitMiniWindow() #

类型

setPiPConfig() #

类型

参数

setPiPSize() #

类型

参数

setGestureConfig() #

类型

参数

notifyWebview() #

类型

参数

WebView 请求 Native API #

WebView 内容事件 #

PiP 事件 #