`<webview>` 标签

警告

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

启用

默认情况下，webview 标签在 Electron >= 5 中是禁用的。您需要通过在构造 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.js 集成，并可以使用 require 和 process 等 Node API 来访问底层系统资源。默认情况下，访客页面禁用 Node.js 集成。

`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 加载，Node 会将 asar: 存档视为虚拟目录。

当访客页面没有 Node.js 集成时，此脚本仍将能够访问所有 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 中的 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 引用者 URL。
- userAgent string (可选) - 发起请求的用户代理。
- extraHeaders string (可选) - 以 "\n" 分隔的额外请求头
- postData (UploadRawData | UploadFile)[] (可选)
- baseURLForDataURL string (可选) - data URL 加载文件时使用的基础 URL（带末尾的路径分隔符）。仅当指定的 url 是 data URL 且需要加载其他文件时才需要此参数。

返回 Promise<void> - 当页面完成加载时，Promise 将解决（请参阅 did-finish-load），如果页面加载失败，Promise 将被拒绝（请参阅 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，它会解析为插入 CSS 的唯一键，以后可以使用该键通过 <webview>.removeInsertedCSS(key) 移除 CSS。

将 CSS 注入当前网页，并返回一个用于插入的样式的唯一键，该键可以在之后通过 <webview>.removeInsertedCSS(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，则被拒绝。

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

`<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% 或缩小 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

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

事件： 'plugin-crashed'

name string
version string

插件进程崩溃时触发。

事件： '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 - 调用菜单的帧的引用者策略。
- 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)`