> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qomicex.top/llms.txt
> Use this file to discover all available pages before exploring further.

# Webview 嵌入

## Webview 嵌入

`Webview` 用沙箱 iframe 嵌入 HTTPS 页面。

```xml theme={null}
<Webview
  Src="https://example.com/embed"
  Height="320"
  Title="公告"
/>
```

## 属性

| 属性 | 可选值 | 默认 | 说明 |
| :- | :- | :- | :- |
| `Src` | HTTPS URL 或绑定 | 必填 | 仅允许 https:443 |
| `Height` | 80–4000 像素 | `320` | iframe 高度 |
| `Title` | 字符串 | `QWidget webview` | iframe 标题 |
| `Allow` | 字符串 | 见下 | iframe `allow` 特性 |
| `Sandbox` | `Scripts` / `Forms` / `Popups` / `Downloads` / `Modals` / `OrientationLock` / `PointerLock` / `Presentation` | `Scripts,Forms,Popups,Downloads` | iframe sandbox 白名单 |
| `Loading` | `Lazy` / `Eager` | `Lazy` | iframe 加载时机 |
| `ReferrerPolicy` | `NoReferrer` / `NoReferrerWhenDowngrade` / `Origin` / `OriginWhenCrossOrigin` / `SameOrigin` / `StrictOrigin` / `StrictOriginWhenCrossOrigin` | `NoReferrer` | referrer 策略 |
| `Fullscreen` | `True` / `False` | `True` | 是否允许全屏 |

默认 `Allow`：

```text theme={null}
fullscreen; autoplay; encrypted-media; picture-in-picture; clipboard-write
```

`Sandbox` 只接受安全白名单；`allow-same-origin`、`allow-top-navigation`、`allow-popups-to-escape-sandbox` 永远不开放。示例：

```xml theme={null}
<Webview Src="https://example.com/embed" Height="320"
         Sandbox="Scripts,Forms,Downloads"
         Loading="Eager" ReferrerPolicy="NoReferrer" Fullscreen="False" />
```

## 链接行为

跨域 iframe 的点击无法被父页面拦截，所以没有“链接在浏览器打开”的 iframe 参数：

* `target="_self"`：在 iframe 内跳转。
* `target="_blank"`：受 `Sandbox` 的 `Popups` 控制；移除 `Popups` 后不会打开弹窗。
* 需要“外部链接一律用系统浏览器打开”时，应使用后端代理重写页面，或改用原生 Webview 的 navigation hook；iframe 本身无法安全实现。

## 安全边界

* `Src` 必须是 HTTPS，且域名必须在编辑器中确认。
* iframe 固定使用 `sandbox="allow-scripts allow-forms allow-popups allow-downloads"`，不包含 `allow-same-origin`，不能访问启动器页面；弹出窗口也不会逃逸沙箱。
* 不能嵌入 `file:`、`data:` 或本地路径。
* 目标站点可能通过 `X-Frame-Options` / CSP 禁止嵌入；这种情况下请使用 `OpenUrl` 在外部浏览器打开。
* 动态 `Src` 的域名仍需在组件 `hosts` 中确认，否则不会渲染。

## 布局

`Webview` 是固定高度块级元素。外层 `Container` 负责裁剪或滚动；不要依赖 iframe 自己改变组件高度。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.