跳到主要内容

<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: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 中的客体页面将集成 Node.js，并可以使用 Node API（如 require 和 process）访问低级系统资源。默认情况下，客体页面中 Node.js 集成是禁用的。

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 加载，后者将 asar: 归档文件视为虚拟目录。

当客体页面没有 Node.js 集成时，此脚本仍然可以访问所有 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 类型，设置页面使用的会话 (session)。如果 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 (可选) - 数据 URL 加载的文件的基础 URL (带有尾部路径分隔符)。仅当指定的 url 是数据 URL 且需要加载其他文件时才需要。

返回 Promise<void> - 当页面加载完成时（参见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 或 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(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，它将在页面中创建用户手势上下文。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 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 - 聚焦并点击选区节点。

停止 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 (可选) - 上边距，单位为英寸。默认为 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 标记，并使用以下 class 将打印值注入其中：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 数据解决 Promise。

将 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)​

返回 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'​

附加到嵌入者 web contents 时触发。

事件：'dom-ready'​

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

事件：'page-title-updated'​

返回

  • title string
  • explicitSet boolean

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

事件：'page-favicon-updated'​

返回

  • favicons string[] - URL 数组。

页面接收到 favicon 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() 无效。

事件：'did-start-navigation'​

返回

  • url string
  • isInPlace boolean
  • isMainFrame boolean
  • frameProcessId Integer
  • frameRoutingId Integer

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

事件：'did-redirect-navigation'​

返回

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

返回

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

事件：'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 中单击链接或在其上下文菜单中为链接选择“在新标签页中打开”时触发。

事件：'devtools-search-query'​

返回

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

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

事件：'devtools-opened'​

DevTools 打开时触发。

事件：'devtools-closed'​

DevTools 关闭时触发。

事件：'devtools-focused'​

DevTools 聚焦/打开时触发。

事件：'context-menu'​

返回

  • 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 - 渲染器是否认为可以进行富文本编辑。

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