<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 非常相似，例如

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 标签具有以下方法

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

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

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

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

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

发起对 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) ​

返回 boolean - 是否可以跳转到 offset 位置。

<webview>.clearHistory() ​

清除导航历史记录。

<webview>.goBack() ​

使客体页面返回。

<webview>.goForward() ​

使客体页面前进。

<webview>.goToIndex(index) ​

导航到指定的绝对索引。

<webview>.goToOffset(offset) ​

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

<webview>.isCrashed() ​

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

<webview>.setUserAgent(userAgent) ​

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

<webview>.getUserAgent() ​

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

<webview>.insertCSS(css) ​

返回 Promise<string> - 一个 Promise，resolve 的值为插入 CSS 的 key，稍后可以使用 <webview>.removeInsertedCSS(key) 删除 CSS。

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

<webview>.removeInsertedCSS(key) ​

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

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

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

返回 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 , y ) 的元素。

<webview>.inspectSharedWorker() ​

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

<webview>.inspectServiceWorker() ​

打开客体页面中存在的 service worker 上下文的 DevTools。

<webview>.setAudioMuted(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) ​

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

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

<webview>.replace(text) ​

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

<webview>.replaceMisspelling(text) ​

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

<webview>.insertText(text) ​

返回 Promise<void>

将 text 插入到焦点元素中。

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

返回 Integer - 请求的请求 ID。

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

<webview>.stopFindInPage(action) ​

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

<webview>.print([options]) ​

返回 Promise<void>

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

<webview>.printToPDF(options) ​

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

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

<webview>.capturePage([rect]) ​

返回 Promise<NativeImage> - 解析为 NativeImage

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

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

返回 Promise<void>

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

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

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

返回 Promise<void>

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

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

<webview>.sendInputEvent(event) ​

返回 Promise<void>

将输入 event 发送到页面。

有关 event 对象的详细说明，请参阅 webContents.sendInputEvent 。

<webview>.setZoomFactor(factor) ​

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

<webview>.setZoomLevel(level) ​

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

<webview>.getZoomFactor() ​

返回 number - 当前缩放比例。

<webview>.getZoomLevel() ​

返回 number - 当前缩放级别。

<webview>.setVisualZoomLevelLimits(minimumLevel, maximumLevel) ​

返回 Promise<void>

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

<webview>.showDefinitionForSelection() macOS ​

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

<webview>.getWebContentsId() ​

返回 number - 此 webview 的 WebContents ID。

DOM 事件 ​

以下 DOM 事件可用于 webview 标签

事件: 'load-commit' ​

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

事件: 'did-finish-load' ​

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

事件: 'did-fail-load' ​

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

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

当框架完成导航时触发。

事件: 'did-start-loading' ​

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

事件: 'did-stop-loading' ​

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

事件: 'did-attach' ​

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

事件: 'dom-ready' ​

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

事件: 'page-title-updated' ​

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

事件: 'page-favicon-updated' ​

当页面接收到 favicon URL 时触发。

事件: 'enter-html-full-screen' ​

当页面通过 HTML API 触发进入全屏模式时触发。

事件: 'leave-html-full-screen' ​

当页面通过 HTML API 触发退出全屏模式时触发。

事件: 'console-message' ​

当来宾窗口记录控制台消息时触发。

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

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

事件: 'found-in-page' ​

当 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' ​

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

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

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

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

事件: 'will-frame-navigate' ​

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

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

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

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

事件: 'did-start-navigation' ​

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

事件: 'did-redirect-navigation' ​

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

事件: 'did-navigate' ​

当导航完成时发出。

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

事件: 'did-frame-navigate' ​

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

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

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

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

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

事件: 'close' ​

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

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

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

事件: 'ipc-message' ​

当来宾页面向嵌入器页面发送异步消息时触发。

使用 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' ​

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

事件: 'destroyed' ​

当 WebContents 被销毁时触发。

事件: 'media-started-playing' ​

当媒体开始播放时发出。

事件: 'media-paused' ​

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

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

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

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

事件: 'update-target-url' ​

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

事件: 'devtools-open-url' ​

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

事件: 'devtools-search-query' ​

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

事件: 'devtools-opened' ​

当 DevTools 打开时发出。

事件: 'devtools-closed' ​

当 DevTools 关闭时发出。

事件: 'devtools-focused' ​

在 DevTools 聚焦/打开时发出。

事件: 'context-menu' ​