`<webview>` 标签

警告

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

启用

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

概述

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

进程：渲染器
此类未从 '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 (OOPIFs) 实现的。webview 标签本质上是一个自定义元素，它使用 shadow DOM 将 iframe 元素包装在其中。

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

当点击 webview 时，页面焦点将从嵌入器帧移至 webview。
您不能为 webview 添加键盘、鼠标和滚动事件监听器。
嵌入器帧和 webview 之间的所有交互都是异步的。

CSS 样式说明

请注意，webview 标签的样式内部使用 display:flex; 来确保当与传统布局和 flexbox 布局一起使用时，子 iframe 元素能够填满其 webview 容器的全部高度和宽度。除非指定 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 中的访客页面将具有 Node 集成，并可以使用 require 和 process 等 Node API 访问底层系统资源。默认情况下，访客页面的 Node 集成是禁用的。

`nodeintegrationinsubframes`

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

一个 boolean，用于为 webview 中的子帧（如 iframe）启用 Node.js 支持的实验性选项。所有预加载脚本都将为每个 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 加载，Node 的 require 会将 asar: 归档视为虚拟目录。

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

`httpreferrer`

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

一个 string，用于设置访客页面的 referrer 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 中的 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 (可选) - 额外的 headers，用 "\n" 分隔
- postData (UploadRawData | UploadFile)[] (可选)
- baseURLForDataURL string (可选) - data URL 加载文件所用的基础 URL（带有尾部路径分隔符）。仅当指定的 url 是 data 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 或 frame）是否仍在加载。

`<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(css) 移除。

`<webview>.removeInsertedCSS(key)`

key string

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

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

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

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

返回 Promise<any> - 一个 Promise，它将以执行代码的结果解析，或者如果代码的结果是已拒绝的 Promise，则被拒绝。

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

`<webview>.openDevTools()`

为访客页面打开一个开发者工具窗口。

`<webview>.closeDevTools()`

关闭访客页面的开发者工具窗口。

`<webview>.isDevToolsOpened()`

返回 boolean - 访客页面是否已附加开发者工具窗口。

`<webview>.isDevToolsFocused()`

返回 boolean - 访客页面的开发者工具窗口是否已获得焦点。

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

x Integer
y Integer

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

`<webview>.inspectSharedWorker()`

为访客页面中存在的共享工作进程上下文打开开发者工具。

`<webview>.inspectServiceWorker()`

为访客页面中存在的服务工作进程上下文打开开发者工具。

`<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 Number (可选) - 移动当前选区开始索引的量。
- end Number (可选) - 移动当前选区结束索引的量。

通过给定的量调整焦点帧中的当前文本选区的开始和结束点。负值将选区向文档开头移动，正值将选区向文档末尾移动。

有关示例，请参阅 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 - 聚焦并点击选区节点。

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

`<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 (可选) - 以英寸为单位的上边距。默认为 1cm（约 0.4 英寸）。
  - bottom number (可选) - 以英寸为单位的下边距。默认为 1cm（约 0.4 英寸）。
  - left number (可选) - 以英寸为单位的左边距。默认为 1cm（约 0.4 英寸）。
  - right number (可选) - 以英寸为单位的右边距。默认为 1cm（约 0.4 英寸）。
- pageRanges string (可选) - 要打印的页面范围，例如 '1-5, 8, 11-13'。默认为空字符串，表示打印所有页面。
- headerTemplate string (可选) - 用于打印页眉的 HTML 模板。应为有效的 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，其上方或下方每增加一个增量，表示缩放比例增加或减少 20%，分别达到原始大小的 300% 和 50% 的默认限制。公式为 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 事件

webview 标签可用的 DOM 事件如下：

事件：'load-commit'

url string
isMainFrame boolean

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

事件：'did-finish-load'

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

事件：'did-fail-load'

errorCode Integer
errorDescription string
validatedURL string
isMainFrame boolean

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

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

isMainFrame boolean

帧完成导航时触发。

事件：'did-start-loading'

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

事件：'did-stop-loading'

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

事件：'did-attach'

附加到嵌入器 webcontents 时触发。

事件: 'dom-ready'

给定帧中的文档加载完成时触发。

事件： 'page-title-updated'

title string
explicitSet boolean

导航期间设置页面标题时触发。当标题是从文件 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 Integer - 日志级别，从 0 到 3。按顺序对应 verbose、info、warning 和 error。
message string - 实际的控制台消息。
line Integer - 触发此控制台消息的源的行号。
sourceId string

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

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

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

事件：'found-in-page'

result Object
- requestId Integer
- activeMatchOrdinal Integer - 活动匹配项的序号。
- matches Integer - 匹配项数量。
- selectionArea Rectangle - 第一个匹配区域的坐标。
- finalUpdate boolean

为 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 Integer
frameRoutingId Integer

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

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

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

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

url string
isInPlace boolean
isMainFrame boolean
frameProcessId Integer
frameRoutingId Integer

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

url string
isInPlace boolean
isMainFrame boolean
frameProcessId Integer
frameRoutingId Integer

在导航过程中发生服务器端重定向后发出。例如 302 重定向。

事件：'did-navigate'

url string

导航完成时发出。

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

事件：'did-frame-navigate'

url string
httpResponseCode Integer - 非 HTTP 导航为 -1
httpStatusText string - 非 HTTP 导航为空，
isMainFrame boolean
frameProcessId Integer
frameRoutingId Integer

任何帧导航完成时发出。

此事件不为页面内导航发出，例如单击锚链接或更新 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 string

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

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

事件：'update-target-url'

url string

鼠标悬停在链接上或键盘将焦点移到链接上时发出。

事件：'devtools-open-url'

url string - 单击或在上下文菜单中选择的链接的 URL。

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

事件：'devtools-search-query'

event Event
query string - 要查询的文本。

在上下文菜单中选择“搜索”文本时发出。

事件：'devtools-opened'

开发者工具打开时发出。

事件：'devtools-closed'

开发者工具关闭时发出。

事件：'devtools-focused'

开发者工具获得焦点/打开时发出。

params Object
- x Integer - x 坐标。
- y Integer - y 坐标。
- linkURL string - 调用上下文菜单的节点所在的链接的 URL。
- linkText string - 与链接关联的文本。如果链接的内容是图像，则可能为空字符串。
- pageURL string - 调用上下文菜单的顶层页面的 URL。
- frameURL string - 调用上下文菜单的子帧的 URL。
- srcURL string - 调用上下文菜单的元素的源 URL。具有源 URL 的元素是图像、音频和视频。
- mediaType string - 调用上下文菜单的节点的类型。可以是 none、image、audio、video、canvas、file 或 plugin。
- hasImageContents boolean - 调用上下文菜单的图像是否具有非空内容。
- isEditable boolean - 上下文是否可编辑。
- selectionText string - 调用上下文菜单的选中文本。
- titleText string - 调用上下文菜单的选中的标题文本。
- altText string - 调用上下文菜单的选中的 alt 文本。
- suggestedFilename string - 在上下文菜单的“链接另存为”选项通过保存文件时使用的建议文件名。
- selectionRect Rectangle - 表示文档空间中选区坐标的矩形。
- selectionStartOffset number - 选中文本的开始位置。
- referrerPolicy Referrer - 调用菜单的帧的 referrer 策略。
- misspelledWord string - 鼠标指针下的拼写错误单词（如果存在）。
- dictionarySuggestions string[] - 一个建议词数组，用于替换 misspelledWord。仅在存在拼写错误单词且拼写检查启用时可用。
- frameCharset string - 调用菜单的帧的字符编码。
- formControlType string - 调用上下文菜单的源。可能的值包括 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 boolean - 如果上下文可编辑，则拼写检查是否启用。
- menuSourceType string - 调用上下文菜单的输入源。可以是 none、mouse、keyboard、touch、touchMenu、longPress、longTap、touchHandle、stylus、adjustSelection 或 adjustSelectionReset。
- mediaFlags Object - 调用上下文菜单的媒体元素的标志。
  - inError boolean - 媒体元素是否已崩溃。
  - isPaused boolean - 媒体元素是否已暂停。
  - isMuted boolean - 媒体元素是否已静音。
  - hasAudio boolean - 媒体元素是否有音频。
  - isLooping boolean - 媒体元素是否正在循环播放。
  - isControlsVisible boolean - 媒体元素的控件是否可见。
  - canToggleControls boolean - 媒体元素的控件是否可切换。
  - canPrint boolean - 媒体元素是否可打印。
  - canSave boolean - 媒体元素是否可下载。
  - canShowPictureInPicture boolean - 媒体元素是否可以显示画中画。
  - isShowingPictureInPicture boolean - 媒体元素当前是否显示画中画。
  - canRotate boolean - 媒体元素是否可以旋转。
  - canLoop boolean - 媒体元素是否可以循环。
- editFlags Object - 这些标志指示渲染器是否认为它可以执行相应的操作。
  - canUndo boolean - 渲染器是否认为它可以撤销。
  - canRedo boolean - 渲染器是否认为它可以重做。
  - canCut boolean - 渲染器是否认为它可以剪切。
  - canCopy boolean - 渲染器是否认为它可以复制。
  - canPaste boolean - 渲染器是否认为它可以粘贴。
  - canDelete boolean - 渲染器是否认为它可以删除。
  - canSelectAll boolean - 渲染器是否认为它可以全选。
  - canEditRichly boolean - 渲染器是否认为它可以富文本编辑。

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

警告
启用
概述
示例
内部实现
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)`