For AI agents: the complete documentation index is available at /apps-plugin/docs/llms.txt, the full documentation bundle is available at /apps-plugin/docs/llms-full.txt, and this page is available as Markdown at /apps-plugin/docs/components/open/web-view.md.

web-view

网页视图组件,用于在应用插件页面内承载 H5 页面。

扫码预览

扫码预览 web-view

Props

属性名类型默认值必填说明
navigationStyle"default" | "custom"'default'否导航栏样式。default 显示组件内置标题栏并避让顶部安全区域;
custom 隐藏内置标题栏,网页内容填满组件区域。

当组件区域与系统安全区重叠时,网页需要自行避让;返回交互也需要按业务需要提供。
具体写法见上方「隐藏标题栏」一节。
前端库版本不低于 0.4.0。
onError(event: { errorCode: number; errorMsg: string; url: string }) => void-否网页加载错误时触发
onLoad(event: { src: string }) => void-否网页加载成功时触发
onMessage(event: { data: unknown }) => void-否网页向应用 postMessage 时触发
refRef<WebViewRef>-否用于获取 WebView 实例方法
srcstring-否网页资源地址,仅支持 https:// 协议;需要在豆包应用插件开放平台配置白名单,并通过校验

Ref 方法

方法名类型说明
postMessage(data: unknown) => void向网页发送消息

与 H5 双向通信

H5 页面需要先引入 WebView JSSDK,才能收发消息。可以用 script 标签引入:

<script src="https://lf3-static.bytednsdoc.com/obj/eden-cn/msvdeh7pfhpquly/doubao-jssdk-0.0.41.js"></script>

H5 项目如果用 npm 管理依赖,也可以安装 @doubao-dev/webview-jssdk 后导入, 导入时会同时挂载全局 window.doubao:

import doubao from '@doubao-dev/webview-jssdk';
// 或按需导入:import { postMessage, onMessage } from '@doubao-dev/webview-jssdk';

H5 可用 API

WebView JSSDK 当前提供以下 API:

API返回值说明
doubao.navigateTo({ url })Promise<unknown>保留当前页面,跳转到应用插件内页面
doubao.navigateBack({ delta? })Promise<unknown>返回应用插件内的上一页或多级页面,delta 默认为 1
doubao.redirectTo({ url })Promise<unknown>关闭当前页面,跳转到应用插件内页面
doubao.reLaunch({ url })Promise<unknown>关闭所有页面,跳转到应用插件内页面
doubao.postMessage({ data })Promise<unknown>向应用侧的 <web-view onMessage> 发送消息
doubao.setTitle({ title })Promise<unknown>设置应用侧 WebView 头部标题
doubao.onMessage(handler)() => void监听应用侧消息,返回注销函数

路由 API 的 url 是应用插件内页面路径,不是 H5 页面地址。

安全限制

  1. URL 协议限制:src 仅支持 https:// 协议,不支持 http://、file:// 等其他协议。
  2. JSB 白名单:白名单外的 JSB 调用会被拦截并返回错误;其他 API 调用需要通过消息通道 交给应用插件页面中转。
  3. 域名校验:需要在豆包应用插件开放平台配置域名白名单,非白名单域名的 URL 将被拒绝加载; 更新域名白名单后,需要重启豆包 App 才能生效。

判断是否在豆包应用插件中打开

H5 可通过 User-Agent 中是否包含 DoubaoApps 判断:

const isInDoubaoApps = navigator.userAgent.includes('DoubaoApps');

双向通信示例

应用侧

src 指向 H5 地址,ref 用于拿到 postMessage,onMessage 接收 H5 消息。

import { useRef } from '@doubao-dev/framework';
import type { WebViewRef } from '@doubao-dev/framework/components';

export default function WebViewPage() {
  const webViewRef = useRef<WebViewRef>(null);

  return (
    <web-view
      ref={webViewRef}
      src="https://example.com/page"
      // 网页加载完成后再发首条消息,H5 才接得住
      onLoad={(event) => webViewRef.current?.postMessage({ type: 'ready', src: event.src })}
      // H5 → 应用:event.data 就是 H5 传入的原始值
      onMessage={(event) => {
        const data = event.data as { type?: string };
        if (data?.type === 'submit') {
          webViewRef.current?.postMessage({ type: 'ack', timestamp: Date.now() });
        }
      }}
      onError={(event) => console.error(event.errorMsg, event.errorCode)}
    />
  );
}

H5 侧

doubao.onMessage 接收应用消息并返回注销函数,doubao.postMessage 发送消息给应用。

const off = doubao.onMessage((raw) => {
  // 应用侧发送的对象会被序列化,这里统一还原
  const data = typeof raw === 'string' ? JSON.parse(raw) : raw;

  if (data.type === 'ready') {
    // H5 → 应用:参数是 { data },不是直接传值
    doubao.postMessage({ data: { type: 'submit', payload: { name: '豆包' } } });
  }
});

// 页面卸载或不再需要时注销
// off();

隐藏标题栏

组件顶部的标题栏(返回按钮 + 标题)默认显示。传入 navigationStyle="custom" 可以隐藏标题栏,让网页内容填满 <web-view> 的组件区域(0.4.0 起支持)。 该配置不会改变组件自身尺寸,也不会自动使组件全屏:

<web-view src="https://example.com/page" navigationStyle="custom" />
navigationStyle表现
default(默认,不传这个属性时就是它)顶部显示标题栏,网页在标题栏下方
custom不显示标题栏,网页内容填满组件区域

custom 模式下需要关注的三件事

  1. 安全区:如果组件区域延伸到屏幕边缘,需要避免内容被状态栏、刘海或底部指示条遮挡 (见下面「安全区」)
  2. 返回:组件不再提供内置返回按钮。系统返回手势仍然可用(会先回退网页历史); 如需提供页面内的退出入口,可调用 doubao.navigateBack()
  3. 标题:没有标题栏,doubao.setTitle 不再有可见效果

安全区

当组件区域可能与系统安全区重叠时,网页需要声明 viewport-fit=cover:

<meta name="viewport" content="width=device-width,initial-scale=1,viewport-fit=cover">

然后用 var() 和 env() 两层取值,四边都要写:

.page {
  padding-top:    var(--safe-area-inset-top,    env(safe-area-inset-top,    0px));
  padding-bottom: var(--safe-area-inset-bottom, env(safe-area-inset-bottom, 0px));
  padding-left:   var(--safe-area-inset-left,   env(safe-area-inset-left,   0px));
  padding-right:  var(--safe-area-inset-right,  env(safe-area-inset-right,  0px));
}

两层都要写的原因:

运行环境env()--safe-area-inset-*
iOS有值不提供
Android WebView(Chromium 140 及以上)有值不提供
Android WebView(Chromium 140 以下)一直是 0由组件提供数值
  • 只写 env():旧版 Android WebView 上内容可能被系统安全区遮挡
  • 只写 var():iOS 上拿不到值
  • 两层都写:三种环境都能正确取值,无需自行判断 WebView 版本

数值单位是 CSS px,不用换算。

注意事项

  • 只给需要避让的内容加 padding:文字和按钮要避开安全区,背景、图片、视频、 画布可以直接铺到边缘,否则边缘会出现空白
  • viewport-fit=cover 必须写:不写的话 iOS 上安全区数值是 0, 旧版 Android WebView 上组件也不会提供数值
  • 注意右上角遮挡:组件区域延伸到屏幕右上角时,「胶囊」按钮可能覆盖网页内容
  • 自行处理返回交互:custom 模式不显示内置返回按钮,有退出需求时需自行提供入口

Web 模拟器差异

Web 模拟器中的 <web-view> 通过本地代理承载 H5 页面,页面脚本读取到的 location.origin / location.host 可能是调试器本地域名,而不是真机 WebView 中的业务域名。 如果 H5 依赖 location.origin 或 location.host 判断测试环境、线上环境、白名单或鉴权逻辑, Web 模拟器结果可能与真机不一致,请使用真机调试确认。