web-view
网页视图组件,用于在应用插件页面内承载 H5 页面。
扫码预览

Props
Ref 方法
与 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 的 url 是应用插件内页面路径,不是 H5 页面地址。
安全限制
- URL 协议限制:
src 仅支持 https:// 协议,不支持 http://、file:// 等其他协议。
- JSB 白名单:白名单外的 JSB 调用会被拦截并返回错误;其他 API 调用需要通过消息通道
交给应用插件页面中转。
- 域名校验:需要在豆包应用插件开放平台配置域名白名单,非白名单域名的 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" />
custom 模式下需要关注的三件事
- 安全区:如果组件区域延伸到屏幕边缘,需要避免内容被状态栏、刘海或底部指示条遮挡
(见下面「安全区」)
- 返回:组件不再提供内置返回按钮。系统返回手势仍然可用(会先回退网页历史);
如需提供页面内的退出入口,可调用
doubao.navigateBack()
- 标题:没有标题栏,
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():旧版 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 模拟器结果可能与真机不一致,请使用真机调试确认。