文档中心

企业直播

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	否	无	原始事件对象。

InitializeWebSDKOfflineOptions

WebSDK 首包离线资源初始化配置。

配置项	类型	是否必选	默认值	说明
enabled	boolean	是	无	是否开启 WebSDK 首包离线资源自动预载。取值为 `true` 时开启；设为 `false` 时保持网络加载，不改变现有行为。
strategy	`'networkOnly' \\| 'preferLocal'`	否	`'networkOnly'`	资源加载策略。取值如下： `networkOnly`：仅使用网络资源，不启用本地入口资源。 `preferLocal`：优先使用已校验的本地入口资源；本地资源不可用时自动回退到 CDN。
accessType	`'pc' \\| 'mobile' \\| 'mobile-all' \\| 'player-pc' \\| 'player-mobile'`	是	无	观播页面实际使用的 WebSDK 接入类型，与 WebSDK Loader 的 `data-access-type` 取值一致。取值如下： `pc`：PC 端，仅支持模块化接入。 `player-pc`：PC 端，单独接入播放器模块。 `mobile`：移动端，支持模块化接入或整页接入。 `mobile-all`：移动端，仅支持整页接入。 `player-mobile`：移动端，单独接入播放器模块。
webSDKVersion	string	否	无	WebSDK 版本号。具体填写规则请参考配置 WebSDK 首包离线资源自动预载。
allowCellularDownload	boolean	否	无	是否允许使用蜂窝网络下载离线资源。未传时使用 SDK 默认策略。
maxDiskBytes	number	否	无	离线入口资源可使用的最大磁盘空间，单位为字节。未传时使用 SDK 默认策略。

PreloadWebSDKOptions

WebSDK 首包离线资源预载配置。

配置项	类型	是否必选	默认值	说明
accessType	InitializeWebSDKOfflineOptions['accessType']	是	无	需要预载的 WebSDK 接入类型，与 WebSDK Loader 的 `data-access-type` 取值一致。
webSDKVersion	string	否	无	WebSDK 版本号。传入时预载指定版本；未传时，SDK 会尝试复用同环境、CDN 域名和 `accessType` 下最近一次 Loader 成功选择的版本。

PreloadResult

WebSDK 首包离线资源预载结果。

配置项	类型	是否必选	默认值	说明
status	`'ready' \\| 'already_ready' \\| 'skipped_no_version' \\| 'skipped_disabled' \\| 'failed'`	是	无	预载结果状态。取值如下： `ready`：入口资源已完成下载和校验，可用于本地加载。 `already_ready`：入口资源此前已完成下载和校验，本次无需重复预载。 `skipped_no_version`：未解析到可预载的 WebSDK 版本，跳过本次预载。 `skipped_disabled`：WebSDK 首包离线资源能力未开启，跳过本次预载。 `failed`：预载失败，可通过 `failureReason` 查看失败原因。
accessType	InitializeWebSDKOfflineOptions['accessType']	是	无	本次预载的 WebSDK 入口资源类型。
requestedVersion	string	否	无	调用方指定的 WebSDK 版本。
resolvedVersion	string	否	无	SDK 实际解析并尝试预载的 WebSDK 版本。
versionSource	`'explicit' \\| 'loader_history'`	否	无	版本来源。取值如下： `explicit`：调用方通过 `webSDKVersion` 显式传入版本。 `loader_history`：SDK 复用最近一次 Loader 成功选择的版本。
failureReason	string	否	无	预载失败原因。仅当 `status` 为 `failed` 时返回。

控制页面生命周期

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 页面。

管理 WebSDK 离线资源

initializeWebSDKOffline()

初始化 WebSDK 首包离线资源能力，并尝试执行首次预载。

类型

(options: InitializeWebSDKOfflineOptions) => Promise<PreloadResult>

说明

普通客户在 App 启动阶段调用一次即可。SDK 会完成缓存、调度、生命周期与资源路由能力初始化，并根据显式版本或历史 Loader 版本尝试首次预载。重复使用相同配置调用时保持幂等。

关于不同接入方式下 webSDKVersion 的填写规则，请参考配置 WebSDK 首包离线资源自动预载。

preloadWebSDK()

在初始化后追加预载 WebSDK 首包入口资源。

类型

(options: PreloadWebSDKOptions) => Promise<PreloadResult>

说明

该方法适用于初始化后，为其他 WebSDK 接入类型提前准备入口资源。例如，从移动端页面进入播放器页前，可预载 player-mobile 对应的入口资源。

getOfflineResourceStatus()

获取 WebSDK 离线资源状态。

类型

() => Record<string, any>

说明

该方法用于排障或统计，可读取当前离线资源的版本、状态、大小和失败原因等诊断信息。

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 请求打开新窗口。
`offlineResourceStateChange`	WebSDK 离线资源状态变化。事件详情包含本次预载或资源切换结果，可参考 `PreloadResult`。

PiP 事件

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

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

最近更新时间：2026.10.30 11:33:29

这个页面对您有帮助吗？

有用

无用

企业直播

IOpenOptions #

IContentIdOptions #

ICloseOptions #

IPiPSize #

IPiPConfig #

IGestureConfig #

ByteLiveEvent #

InitializeWebSDKOfflineOptions #

PreloadWebSDKOptions #

PreloadResult #

控制页面生命周期 #

open() #

类型

参数

close() #

类型

参数

show() #

类型

说明

maximize() #

类型

说明

控制小窗与 PiP #

enterInAppPiP() #

类型

返回值

minimize() #

类型

返回值

exitMiniWindow() #

类型

setPiPConfig() #

类型

参数

setPiPSize() #

类型

参数

setGestureConfig() #

类型

参数

notifyWebview() #

类型

参数

管理 WebSDK 离线资源 #

initializeWebSDKOffline() #

类型

说明

preloadWebSDK() #

类型

说明

getOfflineResourceStatus() #

类型

说明

WebView 请求 Native API #

WebView 内容事件 #

PiP 事件 #