> 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.

# web-view

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

<iframe src="https://developer.doubao.com/docs-preview/component-simulator/?caseId=web-view"
  title="组件示例 web-view"
  width="100%"
  height="700"
  loading="lazy"
  style="width:100%;height:700px;border:0;border-radius:16px;overflow:hidden;"
></iframe>

## 扫码预览

![扫码预览 web-view](https://api.qrserver.com/v1/create-qr-code/?size=200x200\&data=doubao%3A%2F%2Fdoubao_apps%3Fapp_id%3Ddb_1McM5Ni%26path%3D%252Fpages%252Fcomponent%252Fweb-view%252Findex)

## Props

<table>
<thead>
<tr><th width="140">属性名</th><th width="240">类型</th><th width="120">默认值</th><th width="80">必填</th><th width="360">说明</th></tr>
</thead>
<tbody>
<tr><td>navigationStyle</td><td><code>&quot;default&quot; | &quot;custom&quot;</code></td><td>'default'</td><td>否</td><td>导航栏样式。<code>default</code> 显示组件内置标题栏并避让顶部安全区域；<br><code>custom</code> 隐藏内置标题栏，网页内容填满组件区域。<br><br>当组件区域与系统安全区重叠时，网页需要自行避让；返回交互也需要按业务需要提供。<br>具体写法见上方「隐藏标题栏」一节。<br>前端库版本不低于 0.4.0。</td></tr>
<tr><td>onError</td><td><code>(event: { errorCode: number; errorMsg: string; url: string }) =&gt; void</code></td><td>-</td><td>否</td><td>网页加载错误时触发</td></tr>
<tr><td>onLoad</td><td><code>(event: { src: string }) =&gt; void</code></td><td>-</td><td>否</td><td>网页加载成功时触发</td></tr>
<tr><td>onMessage</td><td><code>(event: { data: unknown }) =&gt; void</code></td><td>-</td><td>否</td><td>网页向应用 postMessage 时触发</td></tr>
<tr><td>ref</td><td><code>Ref&lt;WebViewRef&gt;</code></td><td>-</td><td>否</td><td>用于获取 WebView 实例方法</td></tr>
<tr><td>src</td><td><code>string</code></td><td>-</td><td>否</td><td>网页资源地址，仅支持 <code>https://</code> 协议；需要在豆包应用插件开放平台配置白名单，并通过校验</td></tr>
</tbody>
</table>

## Ref 方法

<table>
<thead>
<tr><th width="180">方法名</th><th width="260">类型</th><th width="360">说明</th></tr>
</thead>
<tbody>
<tr><td>postMessage</td><td><code>(data: unknown) =&gt; void</code></td><td>向网页发送消息</td></tr>
</tbody>
</table>

## 与 H5 双向通信

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

```html
<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`：

```js
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` 判断：

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

## 双向通信示例

### 应用侧

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

```tsx
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` 发送消息给应用。

```js
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 起支持）。
该配置不会改变组件自身尺寸，也不会自动使组件全屏：

```tsx
<web-view src="https://example.com/page" navigationStyle="custom" />
```

| navigationStyle          | 表现                |
| ------------------------ | ----------------- |
| `default`（默认，不传这个属性时就是它） | 顶部显示标题栏，网页在标题栏下方  |
| `custom`                 | 不显示标题栏，网页内容填满组件区域 |

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

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

### 安全区

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

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

然后用 `var()` 和 `env()` 两层取值，四边都要写：

```css
.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 模拟器结果可能与真机不一致，请使用真机调试确认。
