`<webview>` 标签

警告

Electron 的 webview 标签基于 Chromium 的 webview，它正在经历重大的架构变更。这会影响 webviews 的稳定性，包括渲染、导航和事件路由。我们目前建议不要使用 webview 标签，并考虑替代方案，例如 iframe、WebContentsView 或完全避免嵌入内容的体系结构。

启用

默认情况下，webview 标签在 Electron >= 5 中处于禁用状态。您需要在构造 BrowserWindow 时设置 webviewTag webPreferences 选项来启用该标签。有关更多信息，请参阅BrowserWindow 构造函数文档。

概述

在隔离的帧和进程中显示外部 Web 内容。

进程：渲染器
此类未从 'electron' 模块导出。它仅作为 Electron API 中其他方法的返回值提供。

使用 webview 标签将“访客”内容（例如网页）嵌入到您的 Electron 应用程序中。访客内容包含在 webview 容器中。应用程序中的嵌入页面控制着访客内容的布局和呈现方式。

与 iframe 不同，webview 在与应用程序不同的进程中运行。它没有与您的网页相同的权限，并且您的应用程序和嵌入内容之间的所有交互将是异步的。这可以保护您的应用程序免受嵌入内容的侵害。

注意

从宿主页面在 webview 上调用的大多数方法都需要同步调用主进程。

示例

要将网页嵌入到您的应用程序中，请将 webview 标签添加到您应用程序的嵌入器页面（这是将显示访客内容的应用程序页面）。最简单的形式是，webview 标签包括网页的 src 和控制 webview 容器外观的 css 样式

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

如果您想以任何方式控制访客内容，您可以编写 JavaScript 来侦听 webview 事件，并使用 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 是使用进程外 iframe (OOPIF) 实现的。 webview 标签本质上是使用 shadow DOM 将 iframe 元素包装在其中的自定义元素。

因此，webview 的行为与跨域 iframe 非常相似，例如

单击 webview 时，页面焦点将从嵌入器帧移动到 webview。
您无法将键盘、鼠标和滚动事件侦听器添加到 webview。
嵌入器帧和 webview 之间的所有反应都是异步的。

CSS 样式注意事项

请注意，webview 标签的样式在内部使用 display:flex; 以确保子 iframe 元素在使用传统和 flexbox 布局时填充其 webview 容器的完整高度和宽度。请不要覆盖默认的 display:flex; CSS 属性，除非指定 display:inline-flex; 用于内联布局。

标签属性

webview 标签具有以下属性

`src`

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

一个表示可见 URL 的 string。写入此属性会启动顶级导航。

将 src 分配给其自身的值将重新加载当前页面。

src 属性也可以接受数据 URL，例如 data:text/plain,Hello, world!。

`nodeintegration`

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

一个 boolean。当存在此属性时，webview 中的访客页面将具有节点集成，并且可以使用诸如 require 和 process 之类的节点 API 来访问底层系统资源。默认情况下，在访客页面中禁用节点集成。

`nodeintegrationinsubframes`

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

一个 boolean，用于启用子帧（例如 webview 内的 iframe）中对 NodeJS 支持的实验性选项。您的所有预加载都将加载到每个 iframe 中，您可以使用 process.isMainFrame 来确定您是否在主帧中。默认情况下，此选项在访客页面中处于禁用状态。

`plugins`

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

一个 boolean。当存在此属性时，webview 中的访客页面将能够使用浏览器插件。默认情况下禁用插件。

`preload`

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

一个 string，用于指定将在访客页面中运行的其他脚本之前加载的脚本。脚本 URL 的协议必须是 file:（即使在使用 asar: 归档文件时），因为它将在底层由 Node 的 require 加载，它将 asar: 归档文件视为虚拟目录。

当访客页面没有节点集成时，此脚本仍然可以访问所有 Node API，但是在该脚本执行完毕后，Node 注入的全局对象将被删除。

`httpreferrer`

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

一个 string，用于设置访客页面的引用 URL。

`useragent`

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

一个 string，用于在页面导航到之前设置访客页面的用户代理。页面加载后，使用 setUserAgent 方法更改用户代理。

`disablewebsecurity`

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

一个 boolean。当存在此属性时，访客页面将禁用 Web 安全性。默认情况下启用 Web 安全性。

此值只能在第一次导航之前修改。

`partition`

<webview src="https://github.com" partition="persist:github"></webview>
<webview src="https://electron.js.cn" partition="electron"></webview>

一个 string，用于设置页面使用的会话。如果 partition 以 persist: 开头，则该页面将使用应用程序中所有具有相同 partition 的页面都可用的持久会话。如果没有 persist: 前缀，则该页面将使用内存中的会话。通过分配相同的 partition，多个页面可以共享相同的会话。如果未设置 partition，则将使用应用程序的默认会话。

此值只能在第一次导航之前修改，因为活动渲染器进程的会话无法更改。随后尝试修改该值的操作将失败并显示 DOM 异常。

`allowpopups`

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

一个 boolean。当存在此属性时，访客页面将被允许打开新窗口。默认情况下禁用弹出窗口。

`webpreferences`

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

一个 string，它是以逗号分隔的字符串列表，用于指定要在 webview 上设置的 Web 首选项。支持的首选项字符串的完整列表可以在 BrowserWindow 中找到。

该字符串的格式与 window.open 中的功能字符串相同。单独的名称被赋予 true 布尔值。可以通过包含 =，后跟该值，将首选项设置为另一个值。特殊值 yes 和 1 被解释为 true，而 no 和 0 被解释为 false。

`enableblinkfeatures`

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

一个 string，它是一个字符串列表，用于指定要启用的 blink 功能，以 , 分隔。支持的功能字符串的完整列表可以在 RuntimeEnabledFeatures.json5 文件中找到。

`disableblinkfeatures`

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

一个 string，它是一个字符串列表，用于指定要禁用的 blink 功能，以 , 分隔。支持的功能字符串的完整列表可以在 RuntimeEnabledFeatures.json5 文件中找到。

方法

webview 标签具有以下方法

注意

必须先加载 webview 元素，然后才能使用这些方法。

示例

const webview = document.querySelector('webview')
webview.addEventListener('dom-ready', () => {
  webview.openDevTools()
})

`<webview>.loadURL(url[, options])`

url URL
options Object (可选)
- httpReferrer (string | Referrer) (可选) - HTTP 引用 url。
- userAgent string (可选) - 发起请求的用户代理。
- extraHeaders string (可选) - 以 "\n" 分隔的额外标头
- postData (UploadRawData | UploadFile)[] (可选)
- baseURLForDataURL string (可选) - 要由数据 url 加载的文件的基本 url（带有尾随路径分隔符）。仅当指定的 url 是数据 url 并且需要加载其他文件时，才需要此操作。

返回 Promise<void> - 当页面完成加载时（请参阅did-finish-load）promise 将解析，如果页面加载失败（请参阅did-fail-load）promise 将拒绝。

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

`<webview>.downloadURL(url[, options])`

url string
options Object (可选)
- headers Record<string, string> (可选) - HTTP 请求标头。

启动对 url 处资源的下载而不进行导航。

`<webview>.getURL()`

返回 string - 访客页面的 URL。

`<webview>.getTitle()`

返回 string - 访客页面的标题。

`<webview>.isLoading()`

返回 boolean - 访客页面是否仍在加载资源。

`<webview>.isLoadingMainFrame()`

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

`<webview>.isWaitingForResponse()`

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

`<webview>.stop()`

停止任何挂起的导航。

`<webview>.reload()`

重新加载访客页面。

`<webview>.reloadIgnoringCache()`

重新加载访客页面并忽略缓存。

`<webview>.canGoBack()`

返回 boolean - 访客页面是否可以后退。

`<webview>.canGoForward()`

返回 boolean - 访客页面是否可以前进。

`<webview>.canGoToOffset(offset)`

offset Integer

返回 boolean - 访客页面是否可以转到 offset。

`<webview>.clearHistory()`

清除导航历史记录。

`<webview>.goBack()`

使访客页面后退。

`<webview>.goForward()`

使访客页面前进。

`<webview>.goToIndex(index)`

index Integer

导航到指定的绝对索引。

`<webview>.goToOffset(offset)`

offset Integer

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

`<webview>.isCrashed()`

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

`<webview>.setUserAgent(userAgent)`

userAgent string

覆盖访客页面的用户代理。

`<webview>.getUserAgent()`

返回 string - 访客页面的用户代理。

`<webview>.insertCSS(css)`

css string

返回 Promise<string> - 一个 promise，它解析为插入的 CSS 的密钥，该密钥稍后可用于通过 <webview>.removeInsertedCSS(key) 删除 CSS。

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

`<webview>.removeInsertedCSS(key)`

key string

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

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

`<webview>.executeJavaScript(code[, userGesture])`

code string
userGesture boolean (可选) - 默认 false。

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

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

`<webview>.openDevTools()`

打开访客页面的 DevTools 窗口。

`<webview>.closeDevTools()`

关闭访客页面的 DevTools 窗口。

`<webview>.isDevToolsOpened()`

返回 boolean - 访客页面是否附加了 DevTools 窗口。

`<webview>.isDevToolsFocused()`

返回 boolean - 访客页面的 DevTools 窗口是否处于焦点。

`<webview>.inspectElement(x, y)`

x Integer
y Integer

开始检查访客页面的位置 (x, y) 处的元素。

`<webview>.inspectSharedWorker()`

打开访客页面中存在的共享 worker 上下文的 DevTools。

`<webview>.inspectServiceWorker()`

为访客页面中存在的 Service Worker 上下文打开开发者工具。

`<webview>.setAudioMuted(muted)`

muted 布尔值

设置访客页面静音。

`<webview>.isAudioMuted()`

返回 boolean - 访客页面是否已静音。

`<webview>.isCurrentlyAudible()`

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

`<webview>.undo()`

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

`<webview>.redo()`

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

`<webview>.cut()`

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

`<webview>.copy()`

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

`<webview>.centerSelection()`

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

`<webview>.paste()`

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

`<webview>.pasteAndMatchStyle()`

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

`<webview>.delete()`

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

`<webview>.selectAll()`

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

`<webview>.unselect()`

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

`<webview>.scrollToTop()`

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

`<webview>.scrollToBottom()`

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

`<webview>.adjustSelection(options)`

options 对象
- start Number（可选） - 移动当前选择的起始索引的量。
- end Number（可选） - 移动当前选择的结束索引的量。

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

有关示例，请参见 webContents.adjustSelection。

`<webview>.replace(text)`

text 字符串

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

`<webview>.replaceMisspelling(text)`

text 字符串

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

`<webview>.insertText(text)`

text 字符串

返回 Promise<void>

将 text 插入到焦点元素。

`<webview>.findInPage(text[, options])`

text 字符串 - 要搜索的内容，不能为空。
options Object (可选)
- forward 布尔值（可选）- 是向前搜索还是向后搜索，默认为 true。
- findNext 布尔值（可选）- 是否使用此请求开始新的文本查找会话。对于初始请求应为 true，对于后续请求应为 false。默认为 false。
- matchCase 布尔值（可选）- 搜索是否应区分大小写，默认为 false。

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

启动请求以查找网页中 text 的所有匹配项。请求的结果可以通过订阅 found-in-page 事件获得。

`<webview>.stopFindInPage(action)`

action 字符串 - 指定结束 <webview>.findInPage 请求时要执行的操作。
- clearSelection - 清除选择。
- keepSelection - 将选择转换为正常选择。
- activateSelection - 聚焦并单击选择节点。

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

`<webview>.print([options])`

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

返回 Promise<void>

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

`<webview>.printToPDF(options)`

options 对象
- landscape 布尔值（可选）- 纸张方向。 true 表示横向，false 表示纵向。默认为 false。
- displayHeaderFooter 布尔值（可选）- 是否显示页眉和页脚。默认为 false。
- printBackground 布尔值（可选）- 是否打印背景图形。默认为 false。
- scale 数字 (可选) - 网页渲染的比例。默认为 1。
- pageSize 字符串 | Size (可选) - 指定生成的 PDF 的页面大小。可以是 A0、A1、A2、A3、A4、A5、A6、Legal、Letter、Tabloid、Ledger 或包含以英寸为单位的 height 和 width 的对象。默认为 Letter。
- margins 对象（可选）
  - top 数字（可选）- 上边距，以英寸为单位。默认为 1 厘米（约 0.4 英寸）。
  - bottom 数字（可选）- 下边距，以英寸为单位。默认为 1 厘米（约 0.4 英寸）。
  - left 数字（可选）- 左边距，以英寸为单位。默认为 1 厘米（约 0.4 英寸）。
  - right 数字（可选）- 右边距，以英寸为单位。默认为 1 厘米（约 0.4 英寸）。
- pageRanges 字符串（可选）- 要打印的页面范围，例如“1-5, 8, 11-13”。默认为空字符串，表示打印所有页面。
- headerTemplate 字符串（可选）- 打印页眉的 HTML 模板。应该是有效的 HTML 标记，并使用以下类将打印值注入到其中：date（格式化的打印日期）、title（文档标题）、url（文档位置）、pageNumber（当前页码）和 totalPages（文档中的总页数）。例如，<span class=title></span> 将生成包含标题的 span。
- footerTemplate 字符串（可选）- 打印页脚的 HTML 模板。应使用与 headerTemplate 相同的格式。
- preferCSSPageSize 布尔值（可选）- 是否首选 CSS 定义的页面大小。默认为 false，在这种情况下，内容将缩放以适应纸张大小。
- generateTaggedPDF 布尔值（可选）实验性 - 是否生成带标签的（可访问的）PDF。默认为 false。由于此属性是实验性的，因此生成的 PDF 可能无法完全遵守 PDF/UA 和 WCAG 标准。
- generateDocumentOutline 布尔值（可选）实验性 - 是否从内容标题生成 PDF 文档轮廓。默认为 false。

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

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

`<webview>.capturePage([rect])`

rect Rectangle (可选) - 要捕获的页面区域。

返回 Promise<NativeImage> - 使用 NativeImage 解析

捕获 rect 内页面的快照。省略 rect 将捕获整个可见页面。

`<webview>.send(channel, ...args)`

channel 字符串
...args any[]

返回 Promise<void>

通过 channel 向渲染器进程发送异步消息，您也可以发送任意参数。渲染器进程可以通过使用 ipcRenderer 模块侦听 channel 事件来处理消息。

有关示例，请参见 webContents.send。

`<webview>.sendToFrame(frameId, channel, ...args)`

frameId [number, number] - [processId, frameId]
channel 字符串
...args any[]

返回 Promise<void>

通过 channel 向渲染器进程发送异步消息，您也可以发送任意参数。渲染器进程可以通过使用 ipcRenderer 模块侦听 channel 事件来处理消息。

有关示例，请参见 webContents.sendToFrame。

`<webview>.sendInputEvent(event)`

event MouseInputEvent | MouseWheelInputEvent | KeyboardInputEvent

返回 Promise<void>

向页面发送输入 event。

有关 event 对象的详细描述，请参见 webContents.sendInputEvent。

`<webview>.setZoomFactor(factor)`

factor 数字 - 缩放因子。

将缩放因子更改为指定的因子。缩放因子是缩放百分比除以 100，因此 300% = 3.0。

`<webview>.setZoomLevel(level)`

level 数字 - 缩放级别。

将缩放级别更改为指定的级别。原始大小为 0，高于或低于 0 的每个增量分别表示缩放到原始大小的 300% 和 50% 的默认限制的 20%。此公式为 scale := 1.2 ^ level。

注意

Chromium 级别的缩放策略是同源的，这意味着特定域的缩放级别会传播到具有相同域的所有窗口实例。区分窗口 URL 将使缩放按窗口工作。

`<webview>.getZoomFactor()`

返回 number - 当前缩放因子。

`<webview>.getZoomLevel()`

返回 number - 当前缩放级别。

`<webview>.setVisualZoomLevelLimits(minimumLevel, maximumLevel)`

minimumLevel 数字
maximumLevel 数字

返回 Promise<void>

设置最大和最小捏合缩放级别。

`<webview>.showDefinitionForSelection()` macOS

显示弹出字典，该字典搜索页面上选定的单词。

`<webview>.getWebContentsId()`

返回 number - 此 webview 的 WebContents ID。

DOM 事件

以下 DOM 事件可用于 webview 标签

事件：'load-commit'

url string
isMainFrame 布尔值

在提交加载时触发。这包括当前文档中的导航以及子框架文档级别的加载，但不包括异步资源加载。

事件：'did-finish-load'

导航完成时触发，即选项卡的微调框将停止旋转，并且会分派 onload 事件。

事件：'did-fail-load'

errorCode 整数
errorDescription 字符串
validatedURL 字符串
isMainFrame 布尔值

此事件类似于 did-finish-load，但在加载失败或取消时触发，例如，调用 window.stop()。

事件：'did-frame-finish-load'

isMainFrame 布尔值

当一个框架完成导航时触发。

事件：'did-start-loading'

与选项卡的微调框开始旋转的时间点相对应。

事件：'did-stop-loading'

与选项卡的微调框停止旋转的时间点相对应。

事件：'did-attach'

连接到嵌入器 Web 内容时触发。

事件：'dom-ready'

在给定框架中的文档加载时触发。

事件：'page-title-updated'

title 字符串
explicitSet 布尔值

在导航期间设置页面标题时触发。当从文件 URL 合成标题时，explicitSet 为 false。

事件：'page-favicon-updated'

favicons string[] - URL 数组。

在页面接收到网站图标 URL 时触发。

事件：'enter-html-full-screen'

当页面进入由 HTML API 触发的全屏时触发。

事件：'leave-html-full-screen'

当页面离开由 HTML API 触发的全屏时触发。

事件：'console-message'

level 整数 - 日志级别，从 0 到 3。按照顺序，它匹配 verbose、info、warning 和 error。
message 字符串 - 实际控制台消息
line 整数 - 触发此控制台消息的源的行号
sourceId 字符串

当访客窗口记录控制台消息时触发。

以下示例代码将所有日志消息转发到嵌入器的控制台，而不考虑日志级别或其他属性。

const webview = document.querySelector('webview')
webview.addEventListener('console-message', (e) => {
  console.log('Guest page logged a message:', e.message)
})

事件：'found-in-page'

result 对象
- requestId 整数
- activeMatchOrdinal 整数 - 活动匹配项的位置。
- matches 整数 - 匹配项数。
- selectionArea Rectangle - 第一个匹配区域的坐标。
- finalUpdate 布尔值

当 webview.findInPage 请求的结果可用时触发。

const webview = document.querySelector('webview')
webview.addEventListener('found-in-page', (e) => {
  webview.stopFindInPage('keepSelection')
})

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

事件：'will-navigate'

url string

当用户或页面想要开始导航时发出。当 window.location 对象发生更改或用户单击页面中的链接时，可能会发生这种情况。

当使用 <webview>.loadURL 和 <webview>.back 等 API 以编程方式启动导航时，不会发出此事件。

在页面内导航期间也不会发出，例如单击锚链接或更新 window.location.hash。为此目的使用 did-navigate-in-page 事件。

调用 event.preventDefault() 无效。

事件: 'will-frame-navigate'

url string
isMainFrame 布尔值
frameProcessId 整数
frameRoutingId 整数

当用户或页面想要在 <webview> 或任何嵌入其中的框架中的任何位置开始导航时发出。当 window.location 对象更改或用户点击页面中的链接时，可能会发生这种情况。

当使用 <webview>.loadURL 和 <webview>.back 等 API 以编程方式启动导航时，不会发出此事件。

在页面内导航期间也不会发出，例如单击锚链接或更新 window.location.hash。为此目的使用 did-navigate-in-page 事件。

调用 event.preventDefault() 无效。

url string
isInPlace 布尔值
isMainFrame 布尔值
frameProcessId 整数
frameRoutingId 整数

当任何框架（包括主框架）开始导航时发出。对于页面内导航，isInPlace 将为 true。

url string
isInPlace 布尔值
isMainFrame 布尔值
frameProcessId 整数
frameRoutingId 整数

在导航期间发生服务器端重定向后发出。例如，302 重定向。

事件: 'did-navigate'

url string

导航完成时发出。

对于页面内导航，例如点击锚点链接或更新 window.location.hash，不会发出此事件。对于此目的，请使用 did-navigate-in-page 事件。

事件: 'did-frame-navigate'

url string
httpResponseCode 整数 - 对于非 HTTP 导航，值为 -1
httpStatusText 字符串 - 对于非 HTTP 导航，为空
isMainFrame 布尔值
frameProcessId 整数
frameRoutingId 整数

当任何框架导航完成时发出。

对于页面内导航，例如点击锚点链接或更新 window.location.hash，不会发出此事件。对于此目的，请使用 did-navigate-in-page 事件。

事件: 'did-navigate-in-page'

isMainFrame 布尔值
url string

当发生页面内导航时发出。

当发生页面内导航时，页面 URL 会更改，但不会导致在页面之外进行导航。发生这种情况的示例包括点击锚点链接或触发 DOM hashchange 事件时。

事件: 'close'

当访客页面尝试关闭自身时触发。

以下示例代码在访客尝试关闭自身时，将 webview 导航到 about:blank。

const webview = document.querySelector('webview')
webview.addEventListener('close', () => {
  webview.src = 'about:blank'
})

事件: 'ipc-message'

frameId [数字，数字] - [processId, frameId] 对。
channel 字符串
args any[]

当访客页面已将异步消息发送到嵌入器页面时触发。

使用 sendToHost 方法和 ipc-message 事件，您可以在访客页面和嵌入器页面之间进行通信

// 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')
})

事件: 'render-process-gone'

details RenderProcessGoneDetails

当渲染器进程意外消失时触发。这通常是因为它崩溃或被终止。

事件: 'plugin-crashed'

name 字符串
version 字符串

当插件进程崩溃时触发。

事件: 'destroyed'

当 WebContents 被销毁时触发。

事件: 'media-started-playing'

当媒体开始播放时发出。

事件: 'media-paused'

当媒体暂停或播放完毕时发出。

事件: 'did-change-theme-color'

themeColor 字符串

当页面的主题颜色更改时发出。这通常是由于遇到 meta 标签

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

事件: 'update-target-url'

url string

当鼠标移动到链接上或键盘将焦点移动到链接上时发出。

事件: 'devtools-open-url'

url 字符串 - 点击或选择的链接的 URL。

当在 DevTools 中点击链接或为其上下文菜单中的链接选择“在新标签页中打开”时发出。

事件: 'devtools-search-query'

event 事件
query 字符串 - 要查询的文本。

当为其上下文菜单中的文本选择“搜索”时发出。

事件: 'devtools-opened'

当 DevTools 打开时发出。

事件: 'devtools-closed'

当 DevTools 关闭时发出。

事件: 'devtools-focused'

当 DevTools 获得焦点/打开时发出。

params 对象
- x 整数 - x 坐标。
- y 整数 - y 坐标。
- linkURL 字符串 - 包含调用上下文菜单的节点的链接的 URL。
- linkText 字符串 - 与链接关联的文本。如果链接的内容是图像，则可能为空字符串。
- pageURL 字符串 - 调用上下文菜单的顶级页面的 URL。
- frameURL 字符串 - 调用上下文菜单的子框架的 URL。
- srcURL 字符串 - 调用上下文菜单的元素的源 URL。具有源 URL 的元素是图像、音频和视频。
- mediaType 字符串 - 调用上下文菜单的节点的类型。可以是 none、image、audio、video、canvas、file 或 plugin。
- hasImageContents 布尔值 - 上下文菜单是否在具有非空内容的图像上调用。
- isEditable 布尔值 - 上下文是否可编辑。
- selectionText 字符串 - 调用上下文菜单的选择的文本。
- titleText 字符串 - 调用上下文菜单的选择的标题文本。
- altText 字符串 - 调用上下文菜单的选择的替代文本。
- suggestedFilename 字符串 - 通过上下文菜单的“链接另存为”选项保存文件时建议使用的文件名。
- selectionRect Rectangle - 表示文档空间中选择的坐标的矩形。
- selectionStartOffset 数字 - 选择文本的起始位置。
- referrerPolicy Referrer - 调用菜单的框架的引用策略。
- misspelledWord 字符串 - 光标下的拼写错误的单词（如果有）。
- dictionarySuggestions 字符串[] - 用于向用户显示以替换 misspelledWord 的建议单词数组。仅当存在拼写错误的单词并且启用了拼写检查器时才可用。
- frameCharset 字符串 - 调用菜单的框架的字符编码。
- formControlType 字符串 - 调用上下文菜单的来源。可能的值包括 none、button-button、field-set、input-button、input-checkbox、input-color、input-date、input-datetime-local、input-email、input-file、input-hidden、input-image、input-month、input-number、input-password、input-radio、input-range、input-reset、input-search、input-submit、input-telephone、input-text、input-time、input-url、input-week、output、reset-button、select-list、select-list、select-multiple、select-one、submit-button 和 text-area。
- spellcheckEnabled 布尔值 - 如果上下文可编辑，则是否启用拼写检查。
- menuSourceType 字符串 - 调用上下文菜单的输入源。可以是 none、mouse、keyboard、touch、touchMenu、longPress、longTap、touchHandle、stylus、adjustSelection 或 adjustSelectionReset。
- mediaFlags 对象 - 调用上下文菜单的媒体元素的标志。
  - inError 布尔值 - 媒体元素是否崩溃。
  - isPaused 布尔值 - 媒体元素是否暂停。
  - isMuted 布尔值 - 媒体元素是否静音。
  - hasAudio 布尔值 - 媒体元素是否具有音频。
  - isLooping 布尔值 - 媒体元素是否循环播放。
  - isControlsVisible 布尔值 - 媒体元素的控件是否可见。
  - canToggleControls 布尔值 - 媒体元素的控件是否可切换。
  - canPrint 布尔值 - 媒体元素是否可以打印。
  - canSave 布尔值 - 是否可以下载媒体元素。
  - canShowPictureInPicture 布尔值 - 媒体元素是否可以显示画中画。
  - isShowingPictureInPicture 布尔值 - 媒体元素当前是否正在显示画中画。
  - canRotate 布尔值 - 媒体元素是否可以旋转。
  - canLoop 布尔值 - 媒体元素是否可以循环。
- editFlags 对象 - 这些标志指示渲染器是否认为它能够执行相应的操作。
  - canUndo 布尔值 - 渲染器是否认为它可以撤消。
  - canRedo 布尔值 - 渲染器是否认为它可以重做。
  - canCut 布尔值 - 渲染器是否认为它可以剪切。
  - canCopy 布尔值 - 渲染器是否认为它可以复制。
  - canPaste 布尔值 - 渲染器是否认为它可以粘贴。
  - canDelete 布尔值 - 渲染器是否认为它可以删除。
  - canSelectAll 布尔值 - 渲染器是否认为它可以选择全部。
  - canEditRichly 布尔值 - 渲染器是否认为它可以以富文本格式编辑文本。

当需要处理新的上下文菜单时发出。

警告
启用
概述
示例
内部实现
CSS 样式说明
标签属性
方法
DOM 事件

警告​

启用​

概述​

示例​

内部实现​

CSS 样式注意事项​

标签属性​

src​

nodeintegration​

nodeintegrationinsubframes​

plugins​

preload​

httpreferrer​

useragent​

disablewebsecurity​

partition​

allowpopups​

webpreferences​

enableblinkfeatures​

disableblinkfeatures​

方法​

<webview>.loadURL(url[, options])​

<webview>.downloadURL(url[, options])​

<webview>.getURL()​

<webview>.getTitle()​

<webview>.isLoading()​

<webview>.isLoadingMainFrame()​

<webview>.isWaitingForResponse()​

<webview>.stop()​

<webview>.reload()​

<webview>.reloadIgnoringCache()​

<webview>.canGoBack()​

<webview>.canGoForward()​

<webview>.canGoToOffset(offset)​

<webview>.clearHistory()​

<webview>.goBack()​

<webview>.goForward()​

<webview>.goToIndex(index)​

<webview>.goToOffset(offset)​

<webview>.isCrashed()​

<webview>.setUserAgent(userAgent)​

<webview>.getUserAgent()​

<webview>.insertCSS(css)​

<webview>.removeInsertedCSS(key)​

<webview>.executeJavaScript(code[, userGesture])​

<webview>.openDevTools()​

<webview>.closeDevTools()​

<webview>.isDevToolsOpened()​

<webview>.isDevToolsFocused()​

<webview>.inspectElement(x, y)​

<webview>.inspectSharedWorker()​

<webview>.inspectServiceWorker()​

<webview>.setAudioMuted(muted)​

<webview>.isAudioMuted()​

<webview>.isCurrentlyAudible()​

<webview>.undo()​

<webview>.redo()​

<webview>.cut()​

<webview>.copy()​

<webview>.centerSelection()​

<webview>.paste()​

<webview>.pasteAndMatchStyle()​

<webview>.delete()​

<webview>.selectAll()​

<webview>.unselect()​

<webview>.scrollToTop()​

<webview>.scrollToBottom()​

<webview>.adjustSelection(options)​

<webview>.replace(text)​

<webview>.replaceMisspelling(text)​

<webview>.insertText(text)​

<webview>.findInPage(text[, options])​

<webview>.stopFindInPage(action)​

<webview>.print([options])​

<webview>.printToPDF(options)​

<webview>.capturePage([rect])​

<webview>.send(channel, ...args)​

<webview>.sendToFrame(frameId, channel, ...args)​

<webview>.sendInputEvent(event)​

<webview>.setZoomFactor(factor)​

警告

启用

概述

示例

内部实现

CSS 样式注意事项

标签属性

`src`

`nodeintegration`

`nodeintegrationinsubframes`

`plugins`

`preload`

`httpreferrer`

`useragent`

`disablewebsecurity`

`partition`

`allowpopups`

`webpreferences`

`enableblinkfeatures`

`disableblinkfeatures`

方法

`<webview>.loadURL(url[, options])`

`<webview>.downloadURL(url[, options])`

`<webview>.getURL()`

`<webview>.getTitle()`

`<webview>.isLoading()`

`<webview>.isLoadingMainFrame()`

`<webview>.isWaitingForResponse()`

`<webview>.stop()`

`<webview>.reload()`

`<webview>.reloadIgnoringCache()`

`<webview>.canGoBack()`

`<webview>.canGoForward()`

`<webview>.canGoToOffset(offset)`

`<webview>.clearHistory()`

`<webview>.goBack()`

`<webview>.goForward()`

`<webview>.goToIndex(index)`

`<webview>.goToOffset(offset)`

`<webview>.isCrashed()`

`<webview>.setUserAgent(userAgent)`

`<webview>.getUserAgent()`

`<webview>.insertCSS(css)`

`<webview>.removeInsertedCSS(key)`

`<webview>.executeJavaScript(code[, userGesture])`

`<webview>.openDevTools()`

`<webview>.closeDevTools()`

`<webview>.isDevToolsOpened()`

`<webview>.isDevToolsFocused()`

`<webview>.inspectElement(x, y)`

`<webview>.inspectSharedWorker()`

`<webview>.inspectServiceWorker()`

`<webview>.setAudioMuted(muted)`

`<webview>.isAudioMuted()`

`<webview>.isCurrentlyAudible()`

`<webview>.undo()`

`<webview>.redo()`

`<webview>.cut()`

`<webview>.copy()`

`<webview>.centerSelection()`

`<webview>.paste()`

`<webview>.pasteAndMatchStyle()`

`<webview>.delete()`

`<webview>.selectAll()`

`<webview>.unselect()`

`<webview>.scrollToTop()`

`<webview>.scrollToBottom()`

`<webview>.adjustSelection(options)`

`<webview>.replace(text)`

`<webview>.replaceMisspelling(text)`

`<webview>.insertText(text)`

`<webview>.findInPage(text[, options])`

`<webview>.stopFindInPage(action)`

`<webview>.print([options])`

`<webview>.printToPDF(options)`

`<webview>.capturePage([rect])`

`<webview>.send(channel, ...args)`

`<webview>.sendToFrame(frameId, channel, ...args)`

`<webview>.sendInputEvent(event)`

`<webview>.setZoomFactor(factor)`