`<webview>` 标签

警告

Electron 的 webview 标签基于 Chromium 的 webview，后者正在经历剧烈的架构变化。这会影响 webview 的稳定性，包括渲染、导航和事件路由。我们目前不建议使用 webview 标签，并建议考虑替代方案，例如 iframe、一个 WebContentsView，或者一种避免嵌入内容的架构。

启用

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

概述

在一个隔离的框架和进程中显示外部网络内容。

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

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

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

注意

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

示例

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

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

如果您想以任何方式控制访客内容，您可以编写侦听 webview 事件并使用 webview 方法响应这些事件的 JavaScript 代码。这是一个包含两个事件侦听器的示例代码：一个侦听网页开始加载，另一个侦听网页停止加载，并在加载期间显示“正在加载...”消息

<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 (OOPIFs) 实现。webview 标签本质上是一个使用 shadow DOM 包装 iframe 元素的自定义元素。

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

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

CSS 样式说明

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

标签属性

webview 标签具有以下属性

`src`

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

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

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

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

`nodeintegration`

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

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

`nodeintegrationinsubframes`

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

一个 boolean，用于启用 webview 内部 iframe（例如 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。当此属性存在时，访客页面的网络安全将被禁用。默认情况下启用网络安全。

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

`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 中的 features 字符串相同的格式。单独的名称将赋予 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 Referrer URL。
- userAgent string (可选) - 发起请求的用户代理。
- extraHeaders string (可选) - 额外的头部信息，用 "\n" 分隔
- postData (UploadRawData | UploadFile)[] (可选)
- baseURLForDataURL string (可选) - 用于通过 data url 加载文件的基础 URL（以尾部路径分隔符结尾）。只有当指定的 url 是 data url 并且需要加载其他文件时才需要此项。

返回 Promise<void> - 当页面加载完成后，Promise 将会 resolve（参见 did-finish-load），如果页面加载失败，Promise 将会 reject（参见 did-fail-load）。

在 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，resolve 的值为插入 CSS 的 key，稍后可以使用 <webview>.removeInsertedCSS(key) 删除 CSS。

将 CSS 注入当前网页，并返回一个用于插入的样式的唯一键，该键可以在之后通过 <webview>.removeInsertedCSS(css) 移除。

`<webview>.removeInsertedCSS(key)`

key string

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

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

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

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

返回 Promise<any> - 一个 Promise，resolve 的值为执行代码的结果，或者如果代码的结果是 rejected 的 Promise，则 reject。

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

`<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 上下文的 DevTools。

`<webview>.setAudioMuted(muted)`

muted boolean

设置客体页面静音。

`<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 Object
- start 数字 (可选) - 移动当前选择的起始索引的量。
- end 数字 (可选) - 移动当前选择的结束索引的量。

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

请参阅 webContents.adjustSelection 以获取示例。

`<webview>.replace(text)`

text string

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

`<webview>.replaceMisspelling(text)`

text string

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

`<webview>.insertText(text)`

text string

返回 Promise<void>

将 text 插入到焦点元素中。

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

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

返回 Integer - 请求的请求 ID。

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

`<webview>.stopFindInPage(action)`

action string - 指定结束 <webview>.findInPage 请求时要执行的操作。
- clearSelection - 清除选区。
- keepSelection - 将选区转换为普通选区。
- activateSelection - 聚焦并点击选区节点。

停止 webview 的任何 findInPage 请求，并提供 action。

`<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（以微米为单位）的对象。

返回 Promise<void>

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

`<webview>.printToPDF(options)`

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

返回 Promise<void>

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

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

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

frameId [number, number] - [processId, frameId]
channel string
...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 number - 缩放比例。

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

`<webview>.setZoomLevel(level)`

level number - 缩放级别。

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

注意

Chromium 级别的缩放策略是同源策略，这意味着特定域的缩放级别会传播到具有相同域的所有窗口实例。区分窗口 URL 将使缩放功能在每个窗口中生效。

`<webview>.getZoomFactor()`

返回 number - 当前缩放比例。

`<webview>.getZoomLevel()`

返回 number - 当前缩放级别。

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

minimumLevel number
maximumLevel number

返回 Promise<void>

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

`<webview>.showDefinitionForSelection()` macOS

显示查找页面上选定单词的弹出式字典。

`<webview>.getWebContentsId()`

返回 number - 此 webview 的 WebContents ID。

DOM 事件

以下 DOM 事件可用于 webview 标签

事件: 'load-commit'

url string
isMainFrame boolean

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

事件: 'did-finish-load'

当导航完成时触发，即选项卡的加载指示器停止旋转，并且分发 onload 事件。

事件: 'did-fail-load'

errorCode 整数
errorDescription 字符串
validatedURL 字符串
isMainFrame boolean

当加载失败或被取消时触发此事件，例如调用 window.stop()。

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

isMainFrame boolean

当框架完成导航时触发。

事件: 'did-start-loading'

对应于选项卡的加载指示器开始旋转的时间点。

事件: 'did-stop-loading'

对应于选项卡的加载指示器停止旋转的时间点。

事件: 'did-attach'

当附加到嵌入器 Web 内容时触发。

事件: 'dom-ready'

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

事件: 'page-title-updated'

title string
explicitSet boolean

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

事件: 'page-favicon-updated'

favicons 字符串[] - URL 数组。

当页面接收到 favicon 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 矩形 - 第一个匹配区域的坐标。
- 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 boolean
frameProcessId 整数
frameRoutingId 整数

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

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

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

调用 event.preventDefault() 不会产生任何效果。

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

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

url string
isInPlace 布尔值
isMainFrame boolean
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 boolean
frameProcessId 整数
frameRoutingId 整数

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

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

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

isMainFrame boolean
url string

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

当页面内导航发生时，页面 URL 会更改，但不会导致页面外部的导航。发生这种情况的示例是单击锚链接或触发 DOM hashchange 事件时。

事件: 'close'

当来宾页面尝试关闭自身时触发。

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

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

事件: 'ipc-message'

frameId [number, number] - [processId, frameId] 对。
channel string
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

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

事件: '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 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 - 触发菜单的框架的 referrer policy。
- 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)`