<webview> 标签¶

<webview id="foo" src="https://www.github.com/" style="display:inline-flex; width:640px; height:480px"></webview>

<script>
  onload = () => {
    const webview = document.querySelector('webview')
    const indicator = document.querySelector('.indicator')

    const loadstart = () => {
      indicator.innerText = 'loading...'
    }

    const loadstop = () => {
      indicator.innerText = ''
    }

    webview.addEventListener('did-start-loading', loadstart)
    webview.addEventListener('did-stop-loading', loadstop)
  }
</script>

<webview src="https://www.github.com/"></webview>

<webview src="https://www.google.com/" nodeintegration></webview>

<webview src="https://www.google.com/" nodeintegrationinsubframes></webview>

<webview src="https://www.github.com/" plugins></webview>

<!-- from a file -->
<webview src="https://www.github.com/" preload="./test.js"></webview>
<!-- or if you want to load from an asar archive -->
<webview src="https://www.github.com/" preload="./app.asar/test.js"></webview>

<webview src="https://www.github.com/" httpreferrer="https://example.com/"></webview>

<webview src="https://www.github.com/" useragent="Mozilla/5.0 (Windows NT 6.1; WOW64; Trident/7.0; AS; rv:11.0) like Gecko"></webview>

<webview src="https://www.github.com/" disablewebsecurity></webview>

<webview src="https://github.com" partition="persist:github"></webview>
<webview src="https://electronjs.org" partition="electron"></webview>

<webview src="https://www.github.com/" allowpopups></webview>

<webview src="https://github.com" webpreferences="allowRunningInsecureContent, javascript=no"></webview>

<webview src="https://www.github.com/" enableblinkfeatures="PreciseMemoryInfo, CSSVariables"></webview>

<webview src="https://www.github.com/" disableblinkfeatures="PreciseMemoryInfo, CSSVariables"></webview>

### `<webview>.loadURL(url[, options])` {#webview-loadurlurl-options}

* `url` URL
* `options` Object（可选）
  * `httpReferrer` (string | [Referrer](structures/referrer.md))（可选）- HTTP Referrer URL。
  * `userAgent` string（可选）- 发起请求的用户代理。
  * `extraHeaders` string（可选）- 以 "\n" 分隔的额外请求头。
  * `postData` ([UploadRawData](structures/upload-raw-data.md) | [UploadFile](structures/upload-file.md))[]（可选）
  * `baseURLForDataURL` string（可选）- 供 data url 加载的文件使用的基础 URL（带尾部路径分隔符）。仅当指定的 `url` 是 data url 且需要加载其他文件时才需要此值。

返回 `Promise<void>` - 当页面完成加载时，该 Promise 将 resolve（参见 [`did-finish-load`](webview-tag.md#event-did-finish-load)）；如果页面加载失败，则 reject（参见 [`did-fail-load`](webview-tag.md#event-did-fail-load)）。

在 webview 中加载 `url`，`url` 必须包含协议前缀，例如 `http://` 或 `file://`。

### `<webview>.downloadURL(url[, options])` {#webview-downloadurlurl-options}

* `url` string
* `options` Object（可选）
  * `headers` Record\<string, string\>（可选）- HTTP 请求头。

在 `url` 处发起资源下载，而不进行导航。

### `<webview>.getURL()` {#webview-geturl}

返回 `string` - 来宾页面的 URL。

### `<webview>.getTitle()` {#webview-gettitle}

返回 `string` - 来宾页面的标题。

### `<webview>.isLoading()` {#webview-isloading}

返回 `boolean` - 来宾页面是否仍在加载资源。

### `<webview>.isLoadingMainFrame()` {#webview-isloadingmainframe}

返回 `boolean` - 主框架（而不仅仅是其中的 iframe 或 frame）是否仍在加载。

### `<webview>.isWaitingForResponse()` {#webview-iswaitingforresponse}

返回 `boolean` - 来宾页面是否正在等待页面主资源的首次响应。

### `<webview>.stop()` {#webview-stop}

停止任何待处理的导航。

### `<webview>.reload()` {#webview-reload}

重新加载来宾页面。

### `<webview>.reloadIgnoringCache()` {#webview-reloadignoringcache}

重新加载来宾页面并忽略缓存。



### `<webview>.canGoBack()` {#webview-can-go-back}

返回 `boolean` - 来宾页面是否可以后退。

### `<webview>.canGoForward()` {#webview-can-go-forward}

返回 `boolean` - 来宾页面是否可以前进。

### `<webview>.canGoToOffset(offset)` {#webview-can-go-to-offset-offset}

* `offset` Integer

返回 `boolean` - 来宾页面是否可以前往 `offset`。

### `<webview>.clearHistory()` {#webview-clear-history}

清除导航历史。

### `<webview>.goBack()` {#webview-go-back}

使来宾页面后退。

### `<webview>.goForward()` {#webview-go-forward}

使来宾页面前进。

### `<webview>.goToIndex(index)` {#webview-go-to-index-index}

* `index` Integer

导航到指定的绝对索引。

### `<webview>.goToOffset(offset)` {#webview-go-to-offset-offset}

* `offset` Integer

导航到相对于“当前条目”的指定偏移量。

### `<webview>.isCrashed()` {#webview-is-crashed}

返回 `boolean` - 渲染进程是否已崩溃。

### `<webview>.setUserAgent(userAgent)` {#webview-set-user-agent-user-agent}

* `userAgent` string

覆盖来宾页面的用户代理。

### `<webview>.getUserAgent()` {#webview-get-user-agent}

返回 `string` - 来宾页面的用户代理。

### `<webview>.insertCSS(css)` {#webview-insert-css-css}

* `css` string

返回 `Promise<string>` - 一个 Promise，解析为插入的 CSS 的键，之后可通过
`<webview>.removeInsertedCSS(key)` 移除该 CSS。

将 CSS 注入当前网页，并返回插入样式表的唯一键。

### `<webview>.removeInsertedCSS(key)` {#webview-remove-inserted-css-key}

* `key` string

返回 `Promise<void>` - 如果移除成功则解析。

从当前网页中移除插入的 CSS。样式表由其键标识，该键由 `<webview>.insertCSS(css)` 返回。

### `<webview>.executeJavaScript(code[, userGesture])` {#webview-execute-javascript-code-user-gesture}

* `code` string
* `userGesture` boolean (optional) - 默认 `false`。

返回 `Promise<any>` - 一个 Promise，解析为执行代码的结果；如果代码的结果是一个被拒绝的 Promise，则会被拒绝。

在页面中评估 `code`。如果设置了 `userGesture`，它将在页面中创建用户手势上下文。像 `requestFullScreen` 这类需要用户操作的 HTML API 可以利用此选项进行自动化。

### `<webview>.openDevTools()` {#webview-open-dev-tools}

为来宾页面打开一个 DevTools 窗口。

### `<webview>.closeDevTools()` {#webview-close-dev-tools}

关闭来宾页面的 DevTools 窗口。

### `<webview>.isDevToolsOpened()` {#webview-is-dev-tools-opened}

返回 `boolean` - 来宾页面是否已附加 DevTools 窗口。

### `<webview>.isDevToolsFocused()` {#webview-is-dev-tools-focused}

返回 `boolean` - 来宾页面的 DevTools 窗口是否处于聚焦状态。

### `<webview>.inspectElement(x, y)` {#webview-inspect-element-x-y}

* `x` Integer
* `y` Integer

开始检查来宾页面位置 (`x`, `y`) 处的元素。

### `<webview>.inspectSharedWorker()` {#webview-inspect-shared-worker}

为来宾页面中存在的共享工作线程上下文打开 DevTools。

### `<webview>.inspectServiceWorker()` {#webview-inspect-service-worker}

为来宾页面中存在的服务工作线程上下文打开 DevTools。

### `<webview>.setAudioMuted(muted)` {#webview-set-audio-muted-muted}

* `muted` boolean

设置来宾页面静音。

### `<webview>.isAudioMuted()` {#webview-is-audio-muted}

返回 `boolean` - 来宾页面是否已静音。

### `<webview>.isCurrentlyAudible()` {#webview-is-currently-audible}

返回 `boolean` - 当前是否正在播放音频。

### `<webview>.undo()` {#webview-undo}

在页面中执行编辑命令 `undo`。

### `<webview>.redo()` {#webview-redo}

在页面中执行编辑命令 `redo`。

### `<webview>.cut()` {#webview-cut}

在页面中执行编辑命令 `cut`。

### `<webview>.copy()` {#webview-copy}

在页面中执行编辑命令 `copy`。

#### `<webview>.centerSelection()` {#webview-center-selection}

在页面中将当前文本选择居中。

### `<webview>.paste()` {#webview-paste}

在页面中执行编辑命令 `paste`。

### `<webview>.pasteAndMatchStyle()` {#webview-paste-and-match-style}

在页面中执行编辑命令 `pasteAndMatchStyle`。

### `<webview>.delete()` {#webview-delete}

在页面中执行编辑命令 `delete`。

### `<webview>.selectAll()` {#webview-select-all}

在页面中执行编辑命令 `selectAll`。

### `<webview>.unselect()` {#webview-unselect}

在页面中执行编辑命令 `unselect`。

#### `<webview>.scrollToTop()` {#webview-scroll-to-top}

滚动到当前 `<webview>` 的顶部。

#### `<webview>.scrollToBottom()` {#webview-scroll-to-bottom}

滚动到当前 `<webview>` 的底部。

#### `<webview>.adjustSelection(options)` {#webview-adjust-selection-options}

* `options` Object
  * `start` Number (optional) - 当前选择起始索引的移动量。
  * `end` Number (optional) - 当前选择结束索引的移动量。

按给定数量调整聚焦框架中当前文本选择的起始点和结束点。负值将选择移向文档开头，正值将选择移向文档结尾。

示例请参见 [`webContents.adjustSelection`](web-contents.md#contentsadjustselectionoptions)。

### `<webview>.replace(text)` {#webview-replace-text}

* `text` string

在页面中执行编辑命令 `replace`。

### `<webview>.replaceMisspelling(text)` {#webview-replace-misspelling-text}

* `text` string

在页面中执行编辑命令 `replaceMisspelling`。

### `<webview>.insertText(text)` {#webview-insert-text-text}

* `text` string

返回 `Promise<void>`

将 `text` 插入到聚焦的元素中。

### `<webview>.findInPage(text[, options])` {#webview-find-in-page-text-options}

* `text` string - 要搜索的内容，不能为空。
* `options` Object (optional)
  * `forward` boolean (optional) - 是否向前或向后搜索，默认为 `true`。
  * `findNext` boolean (optional) - 是否使用此请求开始新的文本查找会话。初始请求应为 `true`，后续请求应为 `false`。默认为 `false`。
  * `matchCase` boolean (optional) - 搜索是否区分大小写，
    默认为 `false`。

返回 `Integer` - 用于该请求的请求 ID。

启动一个请求，以查找网页中 `text` 的所有匹配项。可通过订阅 [`found-in-page`](webview-tag.md#event-found-in-page) 事件获取请求结果。

### `<webview>.stopFindInPage(action)` {#webview-stop-find-in-page-action}

* `action` string - 指定结束
  [`<webview>.findInPage`](#webviewfindinpagetext-options) 请求时要执行的操作。
  * `clearSelection` - 清除选择。
  * `keepSelection` - 将选择转换为普通选择。
  * `activateSelection` - 聚焦并单击选择节点。

使用提供的 `action` 停止 `webview` 的任何 `findInPage` 请求。



### `<webview>.print([options])` {#webview-print-options}

* `options` Object（可选）
  * `silent` boolean（可选）- 不要询问用户打印设置。默认值为 `false`。
  * `printBackground` boolean（可选）- 打印网页的背景颜色和图像。默认值为 `false`。
  * `deviceName` string（可选）- 设置要使用的打印机设备名称。必须是系统定义的名称，而不是“友好”名称，例如 `Brother_QL_820NWB`，而不是 `Brother QL-820NWB`。
  * `color` boolean（可选）- 设置打印的网页是彩色还是灰度。默认值为 `true`。
  * `margins` Object（可选）
    * `marginType` string（可选）- 可以是 `default`、`none`、`printableArea` 或 `custom`。如果选择 `custom`，还需要指定 `top`、`bottom`、`left` 和 `right`。
    * `top` number（可选）- 打印网页的上边距，以像素为单位。
    * `bottom` number（可选）- 打印网页的下边距，以像素为单位。
    * `left` number（可选）- 打印网页的左边距，以像素为单位。
    * `right` number（可选）- 打印网页的右边距，以像素为单位。
  * `landscape` boolean（可选）- 是否以横向模式打印网页。默认值为 `false`。
  * `scaleFactor` number（可选）- 网页的缩放因子。
  * `pagesPerSheet` number（可选）- 每张纸打印的页数。
  * `collate` boolean（可选）- 是否对打印的网页进行整理。
  * `copies` number（可选）- 要打印的网页副本数。
  * `pageRanges` Object[]（可选）- 要打印的页码范围。
    * `from` number - 要打印的第一页的索引（从 0 开始）。
    * `to` number - 要打印的最后一页的索引（包含该页）（从 0 开始）。
  * `duplexMode` string（可选）- 设置打印网页的双面模式。可以是 `simplex`、`shortEdge` 或 `longEdge`。
  * `dpi` Record\<string, number\>（可选）
    * `horizontal` number（可选）- 水平 dpi。
    * `vertical` number（可选）- 垂直 dpi。
  * `header` string（可选）- 作为页眉打印的字符串。
  * `footer` string（可选）- 作为页脚打印的字符串。
  * `pageSize` string | Size（可选）- 指定打印文档的页面大小。可以是 `A3`、
  `A4`、`A5`、`Legal`、`Letter`、`Tabloid`，或一个包含以微米为单位的 `height` 的对象。
  * `usePrinterDefaultPageSize` boolean（可选）- 是否使用系统的默认页面大小。默认值为 `false`。不能与 `pageSize` 一起使用。当提供 `deviceName` 时，使用该特定打印机的默认页面大小。当未提供 `deviceName` 时，使用系统默认打印机的默认页面大小。如果无法获取打印机的默认页面大小，则回退到 A4（210mm x 297mm）。

返回 `Promise<void>`

打印 `webview` 的网页。与 `webContents.print([options])` 相同。

### `<webview>.printToPDF(options)` {#webview-printtopdf-options}

* `options` [PrintToPDFOptions](structures/print-to-pdf-options.md?inline)

返回 `Promise<Uint8Array>` - 以生成的 PDF 数据解析。

将 `webview` 的网页打印为 PDF，与 `webContents.printToPDF(options)` 相同。

### `<webview>.capturePage([rect])` {#webview-capturepage-rect}

<!--
```YAML history
changes:
  - pr-url: https://github.com/electron/electron/pull/53813
    description: "The image now has the page's device scale factor, so `image.getSize()` is in DIPs."
    breaking-changes-header: behavior-changed-captured-page-images-have-the-pages-scale-factor

### 事件：'found-in-page' {#event-found-in-page}

返回：

* `result` Object
  * `requestId` Integer
  * `activeMatchOrdinal` Integer - 活动匹配的位置。
  * `matches` Integer - 匹配数量。
  * `selectionArea` Rectangle - 第一个匹配区域的坐标。
  * `finalUpdate` boolean

当 [`webview.findInPage`](#webviewfindinpagetext-options) 请求的结果可用时触发。

```js @ts-expect-error=[3,6]
const webview = document.querySelector('webview')
webview.addEventListener('found-in-page', (e) => {
  webview.stopFindInPage('keepSelection')
})

const requestId = webview.findInPage('test')
console.log(requestId)

### 事件：'ipc-message' {#event-ipc-message}

返回：

* `frameId` [number, number] - `[processId, frameId]` 对。
* `channel` string
* `args` any[]

当客页向宿主页面发送异步消息时触发。
`frameId` 不会告诉宿主页面哪个文档发送了消息；当这很重要时，让客页使用 `ipcRenderer.send()`，并在主进程中处理客页 `webContents` 的 [`ipc-message`](web-contents.md#event-ipc-message) 事件，其中 `event.senderFrame` 标识发送者。

使用 `sendToHost` 方法和 `ipc-message` 事件，可以在客页和宿主页面之间进行通信：

```js @ts-expect-error=[4,7]
// In embedder page.
const webview = document.querySelector('webview')
webview.addEventListener('ipc-message', (event) => {
  console.log(event.channel)
  // Prints "pong"
})
webview.send('ping')

// In guest page.
const { ipcRenderer } = require('electron')

ipcRenderer.on('ping', () => {
  ipcRenderer.sendToHost('pong')
})

<meta name='theme-color' content='#ff0000'>