as

Settings
Sign out
Notifications
Alexa
亚马逊应用商店
Ring
AWS
文档
Support
Contact Us
My Cases
新手入门
设计和开发
应用发布
参考
支持
原生
Skip to main content
使用Vega WebView组件在Vega OS上集成、优化和交付标准网页应用。本指南涵盖了多个基本工作流,包括桥接网页内容与原生Fire TV功能、确保高性能媒体播放,以及调整网页应用以适应3米观看距离下的电视体验。

将初始焦点设置到WebView

要将焦点设置到WebView,请执行以下操作。在src/App.tsx文件中,通过向WebView组件添加hasTVPreferredFocus={true}hasTVPreferredFocus={true} 属性来设置初始焦点。

在WebView页面发送和接收消息

您可以使用适用于Vega的WebView发送和接收消息。要发送和接收消息,请使用以下选项:
  • 适用于Vega的React Native -> Web: injectJavaScript方法。
  • 网页 -> 适用于Vega的React Native: 道onMessage具。

通过网页实现Vega设备的Fire TV功能

该window.ReactNativeWebView.postMessage方法在 React Native for Vega 中运行该onMessage道具,你可以用它来触发 Vega 设备 Fire TV 功能。window.ReactNativeWebView.postMessage只接受一个参数,它必须是字符串。

在适用于Vega的WebView中检查HDR格式和编解码器支持

WebView在最新的Fire TV设备上支持HEVC Main10(HLG、HDR10、HDR10+)和VP9 Profile2(HLG、HDR10)。最新的Fire TV设备尚不支持AV1 HDR。请勿使用H264和VP8编解码器来处理HDR。 使用canPlayType()或检查 HDR 的可用性isTypeSupported()。

在网页JavaScript中启用后退按钮遥控器按键事件

此allowSystemKeyEvents属性控制网页应用是否会主动侦听特定的系统按键事件,例如后退按钮(由keyCode值要启keyCode: 27用后退按钮遥控器按键事件,请执行以下操作。
  • 在 ** src/App.tsx ** 文件中,将该属性设置为。allowSystemKeyEvents true

启用并使用DevTools进行调试

当您使用调试版本 (__NODE_RUNTIME_ENV__ === "development") 构建应用程序时,Chrome 开发者工具默认处于启用状态。要构建DevTools调试应用,请执行以下操作。
  • 在命令提示符处,运行以下命令。
完成以下步骤以有效使用DevTools。要使用DevTools进行调试,请执行以下操作。
  1. 安装并启动调试应用,这样将打开WebView。
  2. 在命令提示符下,通过运行以下命令执行端口转发。
  3. 打开Google Chrome并导航到chrome://inspect/#devices。
  4. 在Remote Target(远程目标)部分已连接设备列表中,找到DevTools。
  5. 选择inspect(检查)打开DevTools,然后检查WebView。
有关更多信息,请参阅使用Vega Studio调试网页应用。

支持的遥控器按键事件

下表显示了支持的遥控器按键事件及其关联的键代码。

使用canPlayType() 检查HDR的示例

使用isTypeSupported() 检查HDR的示例

不要使用,MediaCapabilities.decodingInfo()因为存在已知问题。它会将VP9 Profile 2支持报告为falsefalse。

使用HEVC的示例

如何覆盖默认媒体控制处理程序

有些应用需要对媒体播放进行精细控制,超出了默认WebView媒体控制的范围。以下是一些示例。
  • 在广告期间禁用搜索操作。
  • 在实时播放期间禁用所有媒体控制。
要实现这种级别的精细控制,开发者有两种选择:
  • 使用 Web 实现navigator.mediaSession。要进行此实现,请allowsDefaultMediaControl出于以下原因启用。
    • 它支持对播放、暂停、向前跳过和向后跳过的传输控制。
    • 它直接在网页中实现,无需更改应用代码。
  • 直接与应用程序代码中的VegaMediaControl界面集成。对于此集成,请allowsDefaultMediaControl出于以下原因禁用。
    • 它提供了对设备媒体控制功能的完全访问权限。
    • 建议将它用于需要深度系统集成的应用。

使用navigator.mediaSession的基于网页的实现

navigator.mediaSessionnavigator.mediaSession属性是一种网页标准,可在网页媒体内容和设备媒体控制系统之间提供强大的接口。它让网页应用能够为当前正在播放的媒体的媒体控制注册操作处理程序,以及自定义针对不同内容的媒体控制行为。 true在 WebView 中设置allowsDefaultMediaControl为时,Alexa 语音命令等系统级控件会传递给注册的自定义处理程序(如果可用)。如果没有已注册的处理程序,WebView会恢复至其默认实现。然后,就可以根据播放上下文(例如在广告或直播期间)使用自定义处理程序。 例如,如果用户说“Alexa, fast forward”(Alexa,快进)且allowsDefaultMediaControlallowsDefaultMediaControl设置为truetrue,则WebView会将命令传递给该网页的向前搜索处理程序(如果该处理程序已注册)。如果开发者未注册处理程序,则WebView会回退到其默认搜索实现。此功能让网页可以根据播放的内容控制搜索行为,例如在广告期间屏蔽搜索。

使用navigator.mediaSession的示例

在应用中集成VegaMediaControl接口

VegaMediaControlVegaMediaControl为Vega应用中的媒体播放管理提供了接口。这种直接集成可实现对媒体功能(例如播放控制、搜索操作等)的精细控制。 要将您的 Vega Web 应用程序与集成 VegaMediaControl,请执行以下关键步骤:
  1. 配置WebView属性。
    • 默认情况下,WebView中的默认媒体控制处于禁用状态。要使控件保持禁用状态,请将道具保持未设置状态或明确设置allowsDefaultMediaControl为false。要使用VegaMediaControl集成,请保持默认媒体控件处于禁用状态。
  2. 实现接VegaMediaControl口。
    • 为您的应用程序添加VegaMediaControl集成
  3. JavaScript桥通信
    • 用于injectJavaScript根据VegaMediaControl处理程序控制网络播放器。

在应用代码中集成VegaMediaControl的示例

以下提供了一个详细示例,演示如何处理暂停、播放、向前搜索和向后搜索命令。所有这些命令都在您的 Vega Web 应用程序VegaMediaControl中使用。
  1. 在 ** manifest. ** tom VegaMediaControl l 中添加对的支持。更新VegaMediaControl的清单以及其他条目。
  2. 在package.json中,添加以下依赖项。
  3. 以下应用代码示例创建了VegaMediaControl服务器和关联的处理程序。这些处理程序可通过自定义行为将JavaScript注入网页。

将存储在设备上的本地文件URL加载到WebView中

默认情况下,WebView从**/pkg/assets**目录加载应用。但是,如果要从其他目录加载应用文件,则必须将属性设置为truetrue。要加载存储在设备上的本地应用文件URL,请执行以下操作。
  • 在 ** src/App.tsx ** 中,将该属性设置为。allowFileAccess true
如果将属性设置为truetrue,会让WebView能够访问并显示所选目录中的应用文件。如果未将allowFileAccessallowFileAccess设置为truetrue,尝试从其他目录加载应用文件时会导致“拒绝访问”错误。文件应用在沙盒环境中运行,限制了其对设备文件系统的访问。下表介绍了文件应用可以访问的目录。

示例: 使用WebView从assets目录加载HTML文件

例如: 使用WebView从应用数据目录加载HTML文件

WebView中的方向键导航

WebView默认启用了空间导航,以提供基本的方向键导航。

阻止WebView中的空间导航

对于实现自定义焦点管理而非默认空间导航焦点的应用,应用在捕获按键按下事件时可以使用Event::preventDefault``Event::preventDefault。这样可以避免自定义焦点逻辑和内置的WebView空间导航之间发生冲突。 要管理序列化的Cookie或清除应用的Cookie,请参阅Vega网页应用Cookie管理器。要查看其他WebView API,请参阅Vega网页应用组件参考。

如何防止页面加载前出现白屏闪烁

在加载网页之前,视图会使用组件的背景颜色。如果未设置背景颜色,则WebView会选择白色背景。要更改背景颜色,请更新WebView组件的backgroundColorbackgroundColor样式。
根据需要修改WebView样式的背景颜色。

如何移除视频播放屏幕顶部的远程播放图标

如果WebView在屏幕顶部显示图标,这可能是disableRemotePlaybackdisableRemotePlayback属性造成的。可以通过将该属性设置为truetrue来移除该图标。该属性为truetrue表示它已被禁用,falsefalse表示它保持启用状态。 示例如下:

如何选择性地允许或阻止HTTP

从WebView版本4.0.2 (RN 0.83) 开始,出于安全考虑,WebView会阻止应用加载纯文本 (HTTP) URL。但是,在某些用例中,应用开发者可能需要加载纯文本URL。可以将应用配置为允许或阻止其应用清单文件中的域。

工作方式

如果清单中没有network-traffic-policy.cleartext章节,则所有 HTTP 请求都将被阻止。仅加载HTTPS URL。此项更改适用于WebView 4.0.2 (RN 0.83) 及更高版本。WebView 3.5.11 (RN 0.72) 或更低版本上的应用不受影响。当同时指定allowed-domains和blocked-domains时,优先blocked-domains考虑。

常见用例

  • 允许除少数域(黑名单)之外的所有HTTP。 示例: 允许对整个应用使用明文,敏感域除外。
  • 阻止除特定域(允许列表)之外的所有HTTP。 示例: 不对整个应用启用明文,但信任特定域。
  • 阻止所有HTTP(无例外)。 示例: 完全不允许使用明文。
  • 允许所有HTTP(无限制)。 示例: 允许对所有域使用明文。也许用于受控门户应用或网络诊断。

相关主题


最后修改于 2026年9月15日