webContents

渲染并控制网页。

进程: 主进程

webContents 是一个 EventEmitter。它负责渲染和控制一个网页，并且是 BrowserWindow 对象的一个属性。访问 webContents 对象的一个例子

const { BrowserWindow } = require('electron')

const win = new BrowserWindow({ width: 800, height: 1500 })
win.loadURL('https://github.com')

const contents = win.webContents
console.log(contents)

导航事件

可以使用几个事件来监控 webContents 中发生的导航。

文档导航

当 webContents 导航到另一个页面时（与 页面内导航 相对），将触发以下事件。

• did-start-navigation
• will-frame-navigate
• will-navigate (仅当主框架导航时触发)
• will-redirect (仅当导航过程中发生重定向时触发)
• did-redirect-navigation (仅当导航过程中发生重定向时触发)
• did-frame-navigate
• did-navigate (仅当主框架导航时触发)

如果在任何可取消事件上调用了 event.preventDefault()，则后续事件将不会触发。

页面内导航

页面内导航不会导致页面重新加载，而是导航到当前页面内的位置。这些事件是不可取消的。对于页面内导航，以下事件将按此顺序触发

• did-start-navigation
• did-navigate-in-page

框架导航

will-navigate 和 did-navigate 事件仅在 主框架 导航时触发。如果您还想观察 <iframe> 中的导航，请使用 will-frame-navigate 和 did-frame-navigate 事件。

方法

这些方法可以从 webContents 模块访问

const { webContents } = require('electron')

console.log(webContents)

webContents.getAllWebContents()

返回 WebContents[] - 所有 WebContents 实例的数组。这将包含所有窗口、webview、打开的 DevTools 和 DevTools 扩展后台页面的 Web 内容。

webContents.getFocusedWebContents()

返回 WebContents | null - 此应用程序中获得焦点的 Web 内容，否则返回 null。

webContents.fromId(id)

• id Integer

返回 WebContents | undefined - 具有给定 ID 的 WebContents 实例，或者如果与给定 ID 没有关联的 WebContents，则返回 undefined。

webContents.fromFrame(frame)

• frame WebFrameMain

返回 WebContents | undefined - 具有给定 WebFrameMain 的 WebContents 实例，或者如果与给定 WebFrameMain 没有关联的 WebContents，则返回 undefined。

webContents.fromDevToolsTargetId(targetId)

• targetId string - Chrome DevTools Protocol TargetID 与 WebContents 实例关联。

返回 WebContents | undefined - 具有给定 TargetID 的 WebContents 实例，或者如果与给定 TargetID 没有关联的 WebContents，则返回 undefined。

在与 Chrome DevTools Protocol 通信时，基于其分配的 TargetID 查找 WebContents 实例可能很有用。

async function lookupTargetId (browserWindow) {
  const wc = browserWindow.webContents
  await wc.debugger.attach('1.3')
  const { targetInfo } = await wc.debugger.sendCommand('Target.getTargetInfo')
  const { targetId } = targetInfo
  const targetWebContents = await wc.fromDevToolsTargetId(targetId)
}

类: WebContents

渲染并控制 BrowserWindow 实例的内容。

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

实例事件

事件: 'did-finish-load'

在导航完成时发出，即选项卡的加载指示器停止旋转，并且调度了 onload 事件。

事件: 'did-fail-load'

返回

• event Event
• errorCode Integer
• errorDescription string
• validatedURL string
• isMainFrame boolean
• frameProcessId Integer
• frameRoutingId Integer

此事件类似于 did-finish-load，但在加载失败时发出。完整的错误代码列表及其含义可在 此处 找到。

事件: 'did-fail-provisional-load'

返回

• event Event
• errorCode Integer
• errorDescription string
• validatedURL string
• isMainFrame boolean
• frameProcessId Integer
• frameRoutingId Integer

此事件类似于 did-fail-load，但在加载被取消时发出（例如，调用了 window.stop()）。

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

返回

• event Event
• isMainFrame boolean
• frameProcessId Integer
• frameRoutingId Integer

当框架完成导航时发出。

事件: 'did-start-loading'

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

事件: 'did-stop-loading'

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

事件: 'dom-ready'

在顶级框架中的文档加载时发出。

事件: 'page-title-updated'

返回

• event Event
• title string
• explicitSet boolean

在导航期间设置页面标题时触发。如果标题是从文件 URL 合成而来，则 explicitSet 为 false。

事件: 'page-favicon-updated'

返回

• event Event
• favicons string[] - URL 数组。

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

事件: 'content-bounds-updated'

返回

• event Event
• bounds Rectangle - 请求的新内容边界

当页面调用 window.moveTo、window.resizeTo 或相关 API 时发出。

默认情况下，这将移动窗口。要防止此行为，请调用 event.preventDefault()。

事件: 'did-create-window'

返回

• window BrowserWindow
• details Object
  • url string - 创建的窗口的 URL。
  • frameName string - 在 window.open() 调用中为创建的窗口指定的名称。
  • options BrowserWindowConstructorOptions - 用于创建 BrowserWindow 的选项。它们以优先级递增的顺序合并：从 window.open() 的 features 字符串中解析的选项、从父级继承的安全相关 webPreferences 以及由 webContents.setWindowOpenHandler 给定的选项。未识别的选项不会被过滤掉。
  • referrer Referrer - 将传递给新窗口的引用者。根据引用者策略，Referer 标头可能不会发送。
  • postBody PostBody (可选) - 将与适当的标头一起发送到新窗口的 POST 数据。如果未发送 POST 数据，则该值为 null。仅当窗口由将 target=_blank 设置为 form 创建时才定义。
  • disposition string - 可以是 default、foreground-tab、background-tab、new-window 或 other。

在通过渲染器中的 window.open 成功创建窗口之后发出。如果从 webContents.setWindowOpenHandler 取消了窗口的创建，则不会发出。

有关更多详细信息以及如何将其与 webContents.setWindowOpenHandler 结合使用，请参阅 window.open()。

事件: 'will-navigate'

返回

• details 事件<>
  • url string - 框架正在导航到的 URL。
  • isSameDocument boolean - 此事件不会为使用 window.history API 和引用片段导航的相同文档导航触发。此属性始终设置为此事件的 false。
  • isMainFrame boolean - 如果导航发生在主框架中，则为 true。
  • frame WebFrameMain | null - 要导航的框架。如果访问后框架已导航或销毁，则可能为 null。
  • initiator WebFrameMain | null (可选) - 发起导航的框架，可以是父框架（例如，通过带有框架名称的 window.open），或者如果导航不是由框架发起的，则为 null。如果发起框架在发出事件之前被删除，则也可能为 null。
• url string 已弃用
• isInPlace boolean 已弃用
• isMainFrame boolean 已弃用
• frameProcessId Integer 已弃用
• frameRoutingId Integer 已弃用

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

此事件不会在通过 webContents.loadURL 和 webContents.back 等 API 以编程方式启动导航时发出。

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

调用 event.preventDefault() 将阻止导航。

事件: 'will-frame-navigate'

返回

• details 事件<>
  • url string - 框架正在导航到的 URL。
  • isSameDocument boolean - 此事件不会为使用 window.history API 和引用片段导航的相同文档导航触发。此属性始终设置为此事件的 false。
  • isMainFrame boolean - 如果导航发生在主框架中，则为 true。
  • frame WebFrameMain | null - 要导航的框架。如果访问后框架已导航或销毁，则可能为 null。
  • initiator WebFrameMain | null (可选) - 发起导航的框架，可以是父框架（例如，通过带有框架名称的 window.open），或者如果导航不是由框架发起的，则为 null。如果发起框架在发出事件之前被删除，则也可能为 null。

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

与 will-navigate 不同，will-frame-navigate 在主框架或其任何子框架尝试导航时触发。当导航事件来自主框架时，isMainFrame 将为 true。

此事件不会在通过 webContents.loadURL 和 webContents.back 等 API 以编程方式启动导航时发出。

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

调用 event.preventDefault() 将阻止导航。

事件: 'did-start-navigation'

返回

• details 事件<>
  • url string - 框架正在导航到的 URL。
  • isSameDocument 布尔值 - 是否在不改变文档的情况下发生了导航。相同文档导航的例子包括引用片段导航、pushState/replaceState 以及同页历史导航。
  • isMainFrame boolean - 如果导航发生在主框架中，则为 true。
  • frame WebFrameMain | null - 要导航的框架。如果访问后框架已导航或销毁，则可能为 null。
  • initiator WebFrameMain | null (可选) - 发起导航的框架，可以是父框架（例如，通过带有框架名称的 window.open），或者如果导航不是由框架发起的，则为 null。如果发起框架在发出事件之前被删除，则也可能为 null。
• url string 已弃用
• isInPlace boolean 已弃用
• isMainFrame boolean 已弃用
• frameProcessId Integer 已弃用
• frameRoutingId Integer 已弃用

当任何框架（包括主框架）开始导航时发出。

事件: 'will-redirect'

返回

• details 事件<>
  • url string - 框架正在导航到的 URL。
  • isSameDocument 布尔值 - 是否在不改变文档的情况下发生了导航。相同文档导航的例子包括引用片段导航、pushState/replaceState 以及同页历史导航。
  • isMainFrame boolean - 如果导航发生在主框架中，则为 true。
  • frame WebFrameMain | null - 要导航的框架。如果访问后框架已导航或销毁，则可能为 null。
  • initiator WebFrameMain | null (可选) - 发起导航的框架，可以是父框架（例如，通过带有框架名称的 window.open），或者如果导航不是由框架发起的，则为 null。如果发起框架在发出事件之前被删除，则也可能为 null。
• url string 已弃用
• isInPlace boolean 已弃用
• isMainFrame boolean 已弃用
• frameProcessId Integer 已弃用
• frameRoutingId Integer 已弃用

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

此事件将在相同的导航中，在 did-start-navigation 之后且 did-redirect-navigation 事件之前发出。

调用 event.preventDefault() 将阻止导航（不仅仅是重定向）。

事件: 'did-redirect-navigation'

返回

• details 事件<>
  • url string - 框架正在导航到的 URL。
  • isSameDocument 布尔值 - 是否在不改变文档的情况下发生了导航。相同文档导航的例子包括引用片段导航、pushState/replaceState 以及同页历史导航。
  • isMainFrame boolean - 如果导航发生在主框架中，则为 true。
  • frame WebFrameMain | null - 要导航的框架。如果访问后框架已导航或销毁，则可能为 null。
  • initiator WebFrameMain | null (可选) - 发起导航的框架，可以是父框架（例如，通过带有框架名称的 window.open），或者如果导航不是由框架发起的，则为 null。如果发起框架在发出事件之前被删除，则也可能为 null。
• url string 已弃用
• isInPlace boolean 已弃用
• isMainFrame boolean 已弃用
• frameProcessId Integer 已弃用
• frameRoutingId Integer 已弃用

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

此事件无法阻止，如果想要阻止重定向，请查看上面的 will-redirect 事件。

事件: 'did-navigate'

返回

• event Event
• url string
• httpResponseCode 整数 - 非 HTTP 导航为 -1
• httpStatusText 字符串 - 非 HTTP 导航为空字符串

当主框架导航完成时发出。

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

事件: 'did-frame-navigate'

返回

• event Event
• url string
• httpResponseCode 整数 - 非 HTTP 导航为 -1
• httpStatusText 字符串 - 非 HTTP 导航为空字符串，
• isMainFrame boolean
• frameProcessId Integer
• frameRoutingId Integer

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

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

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

返回

• event Event
• url string
• isMainFrame boolean
• frameProcessId Integer
• frameRoutingId Integer

当任何框架中发生页面内导航时发出。

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

事件: 'will-prevent-unload'

返回

• event Event

当 beforeunload 事件处理程序尝试取消页面卸载时发出。

调用 event.preventDefault() 将忽略 beforeunload 事件处理程序并允许页面卸载。

const { BrowserWindow, dialog } = require('electron')

const win = new BrowserWindow({ width: 800, height: 600 })
win.webContents.on('will-prevent-unload', (event) => {
  const choice = dialog.showMessageBoxSync(win, {
    type: 'question',
    buttons: ['Leave', 'Stay'],
    title: 'Do you want to leave this site?',
    message: 'Changes you made may not be saved.',
    defaultId: 0,
    cancelId: 1
  })
  const leave = (choice === 0)
  if (leave) {
    event.preventDefault()
  }
})

注意

此事件将为 BrowserViews 发出，但不会被尊重 - 这是因为我们选择不将 BrowserView 的生命周期与其拥有的 BrowserWindow 绑定，如果存在的话，具体请参考 规范。

事件: 'render-process-gone'

返回

• event Event
• details RenderProcessGoneDetails

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

事件: 'unresponsive'

当网页无响应时发出。

事件: 'responsive'

当无响应的网页再次响应时发出。

事件: 'destroyed'

当 webContents 被销毁时发出。

事件: 'input-event'

返回

• event Event
• inputEvent InputEvent

当输入事件发送到 WebContents 时发出。有关详细信息，请参阅 InputEvent。

事件: 'before-input-event'

返回

• event Event
• input 对象 - 输入属性。
  • type 字符串 - keyUp 或 keyDown。
  • key 字符串 - 等同于 KeyboardEvent.key。
  • code 字符串 - 等同于 KeyboardEvent.code。
  • isAutoRepeat 布尔值 - 等同于 KeyboardEvent.repeat。
  • isComposing 布尔值 - 等同于 KeyboardEvent.isComposing。
  • shift 布尔值 - 等同于 KeyboardEvent.shiftKey。
  • control 布尔值 - 等同于 KeyboardEvent.controlKey。
  • alt 布尔值 - 等同于 KeyboardEvent.altKey。
  • meta 布尔值 - 等同于 KeyboardEvent.metaKey。
  • location 数字 - 等同于 KeyboardEvent.location。
  • modifiers 字符串数组 - 请参阅 InputEvent.modifiers。

在页面中分发 keydown 和 keyup 事件之前发出。调用 event.preventDefault 将阻止页面 keydown/keyup 事件和菜单快捷键。

要仅阻止菜单快捷键，请使用 setIgnoreMenuShortcuts

const { app, BrowserWindow } = require('electron')

app.whenReady().then(() => {
  const win = new BrowserWindow({ width: 800, height: 600 })

  win.webContents.on('before-input-event', (event, input) => {
    // Enable application menu keyboard shortcuts when Ctrl/Cmd are down.
    win.webContents.setIgnoreMenuShortcuts(!input.control && !input.meta)
  })
})

事件: 'before-mouse-event'

返回

• event Event
• mouse MouseInputEvent

在页面中分发鼠标事件之前发出。

调用 event.preventDefault 将阻止页面鼠标事件。

const { app, BrowserWindow } = require('electron')

app.whenReady().then(() => {
  const win = new BrowserWindow({ width: 800, height: 600 })

  win.webContents.on('before-mouse-event', (event, mouse) => {
    // Prevent mouseDown events.
    if (mouse.type === 'mouseDown') {
      console.log(mouse)
      /*
      {
        type: 'mouseDown',
        clickCount: 1,
        movementX: 0,
        movementY: 0,
        button: 'left',
        x: 632.359375,
        y: 480.6875,
        globalX: 168.359375,
        globalY: 193.6875
      }
      */
      event.preventDefault()
    }
  })
})

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

当窗口通过 HTML API 触发时进入全屏状态时发出。

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

当窗口通过 HTML API 触发时退出全屏状态时发出。

事件: 'zoom-changed'

返回

• event Event
• zoomDirection 字符串 - 可以是 in 或 out。

当用户请求使用鼠标滚轮更改缩放级别时发出。

事件: 'blur'

当 WebContents 失去焦点时发出。

事件: 'focus'

当 WebContents 获得焦点时发出。

请注意，在 macOS 上，拥有焦点意味着 WebContents 是窗口的第一响应者，因此在同一窗口中的不同 WebContents 和 BrowserView 之间切换焦点不会触发 WebContents 的 focus 和 blur 事件，因为每个窗口的第一响应者没有改变。

WebContents 的 focus 和 blur 事件仅应用于检测同一窗口中不同 WebContents 和 BrowserView 之间的焦点更改。

事件: 'devtools-open-url'

返回

• event Event
• url 字符串 - 单击或选择的链接的 URL。

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

事件: 'devtools-search-query'

返回

• event Event
• query 字符串 - 要查询的文本。

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

事件: 'devtools-opened'

当 DevTools 打开时发出。

事件: 'devtools-closed'

当 DevTools 关闭时发出。

事件: 'devtools-focused'

当 DevTools 获得焦点/打开时发出。

事件: 'certificate-error'

返回

• event Event
• url string
• error 字符串 - 错误代码。
• certificate Certificate
• callback Function
  • isTrusted 布尔值 - 指示是否可以认为证书是受信任的。
• isMainFrame boolean

当验证 url 的 certificate 失败时发出。

用法与 app 的 certificate-error 事件 相同。

事件: 'select-client-certificate'

返回

• event Event
• url URL
• certificateList Certificate[]
• callback Function
  • certificate Certificate - 必须是给定列表中的证书。

当请求客户端证书时发出。

用法与 app 的 select-client-certificate 事件 相同。

事件: 'login'

返回

• event Event
• authenticationResponseDetails 对象
  • url URL
• authInfo Object
  • isProxy boolean
  • scheme string
  • host string
  • port Integer
  • realm string
• callback Function
  • username string (可选)
  • password string (可选)

当 webContents 想要执行基本身份验证时发出。

用法与 app 的 login 事件 相同。

事件: 'found-in-page'

返回

• event Event
• result 对象
  • requestId 整数
  • activeMatchOrdinal 整数 - 活动匹配项的位置。
  • matches 整数 - 匹配项数量。
  • selectionArea 矩形 - 第一个匹配区域的坐标。
  • finalUpdate 布尔值

当 webContents.findInPage 请求的结果可用时发出。

事件: 'media-started-playing'

当媒体开始播放时发出。

事件: 'media-paused'

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

事件: 'audio-state-changed'

返回

• event Event<>
  • audible 布尔值 - 如果一个或多个框架或子 webContents 正在发出音频，则为 true。

当媒体变为可听或不可听时发出。

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

返回

• event Event
• color (字符串 | null) - 主题颜色格式为 '#rrggbb'。如果没有设置主题颜色，则为 null。

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

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

事件: 'update-target-url'

返回

• event Event
• url string

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

事件: 'cursor-changed'

返回

• event Event
• type 字符串
• image NativeImage (可选)
• scale Float (可选) - 自定义光标的缩放因子。
• size Size (可选) - image 的尺寸。
• hotspot Point (可选) - 自定义光标的热点坐标。

当光标类型改变时发出。type 参数可以是 pointer, crosshair, hand, text, wait, help, e-resize, n-resize, ne-resize, nw-resize, s-resize, se-resize, sw-resize, w-resize, ns-resize, ew-resize, nesw-resize, nwse-resize, col-resize, row-resize, m-panning, m-panning-vertical, m-panning-horizontal, e-panning, n-panning, ne-panning, nw-panning, s-panning, se-panning, sw-panning, w-panning, move, vertical-text, cell, context-menu, alias, progress, nodrop, copy, none, not-allowed, zoom-in, zoom-out, grab, grabbing, custom, null, drag-drop-none, drag-drop-move, drag-drop-copy, drag-drop-link, ns-no-resize, ew-no-resize, nesw-no-resize, nwse-no-resize, 或 default。

如果 type 参数是 custom，则 image 参数将包含自定义光标图像，类型为 NativeImage，并且 scale、size 和 hotspot 将包含有关自定义光标的附加信息。

事件: 'context-menu'

返回

• event Event
• params 对象
  • x 整数 - x 坐标。
  • y 整数 - y 坐标。
  • frame WebFrameMain | null - 触发上下文菜单的框架。如果框架已导航或销毁，则可能为 null。
  • 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 布尔值 - 渲染器是否可以丰富地编辑文本。

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

事件: 'select-bluetooth-device'

返回

• event Event
• devices BluetoothDevice[]
• callback Function
  • deviceId 字符串

当对 navigator.bluetooth.requestDevice 进行调用时需要选择蓝牙设备时发出。应使用所选设备的 deviceId 调用 callback。将空字符串传递给 callback 将取消请求。

如果没有为该事件添加事件侦听器，则将取消所有蓝牙请求。

如果处理此事件时未调用 event.preventDefault，则将自动选择第一个可用设备。

由于蓝牙的性质，在调用 navigator.bluetooth.requestDevice 时扫描设备可能需要时间，并且将多次触发 select-bluetooth-device，直到使用设备 ID 或空字符串取消请求来调用 callback。

main.js

const { app, BrowserWindow } = require('electron')

let win = null

app.whenReady().then(() => {
  win = new BrowserWindow({ width: 800, height: 600 })
  win.webContents.on('select-bluetooth-device', (event, deviceList, callback) => {
    event.preventDefault()
    const result = deviceList.find((device) => {
      return device.deviceName === 'test'
    })
    if (!result) {
      // The device wasn't found so we need to either wait longer (eg until the
      // device is turned on) or cancel the request by calling the callback
      // with an empty string.
      callback('')
    } else {
      callback(result.deviceId)
    }
  })
})

事件: 'paint'

返回

• details 事件<>
  • texture OffscreenSharedTexture (可选) 实验性 - 当 webPreferences.offscreen.useSharedTexture 为 true 时，帧的 GPU 共享纹理。
• dirtyRect Rectangle
• image NativeImage - 整个帧的图像数据。

当生成新帧时发出。仅将脏区域传递到缓冲区中。

const { BrowserWindow } = require('electron')

const win = new BrowserWindow({ webPreferences: { offscreen: true } })
win.webContents.on('paint', (event, dirty, image) => {
  // updateBitmap(dirty, image.toBitmap())
})
win.loadURL('https://github.com')

在使用共享纹理（将 webPreferences.offscreen.useSharedTexture 设置为 true）功能时，可以将纹理句柄传递到外部渲染管道，而无需在 CPU 和 GPU 内存之间复制数据，并具有 Chromium 的硬件加速支持。此功能对于高性能渲染场景很有帮助。

只能同时存在有限数量的纹理，因此在完成纹理后尽快调用 texture.release() 非常重要。通过自己管理纹理生命周期，可以安全地通过 IPC 将 texture.textureInfo 传递到其他进程。

更多详细信息请参见 离屏渲染教程。要了解如何在本机代码中处理纹理，请参阅 离屏渲染的代码文档。。

const { BrowserWindow } = require('electron')

const win = new BrowserWindow({ webPreferences: { offscreen: { useSharedTexture: true } } })
win.webContents.on('paint', async (e, dirty, image) => {
  if (e.texture) {
    // By managing lifecycle yourself, you can handle the event in async handler or pass the `e.texture.textureInfo`
    // to other processes (not `e.texture`, the `e.texture.release` function is not passable through IPC).
    await new Promise(resolve => setTimeout(resolve, 50))

    // You can send the native texture handle to native code for importing into your rendering pipeline.
    // Read more at https://github.com/electron/electron/blob/main/shell/browser/osr/README.md
    // importTextureHandle(dirty, e.texture.textureInfo)

    // You must call `e.texture.release()` as soon as possible, before the underlying frame pool is drained.
    e.texture.release()
  }
})
win.loadURL('https://github.com')

事件: 'devtools-reload-page'

当 DevTools 窗口指示 webContents 重新加载时发出

事件: 'will-attach-webview'

返回

• event Event
• webPreferences WebPreferences - 将由来宾页面使用的 web 首选项。可以修改此对象以调整来宾页面的首选项。
• params Record<string, string> - 其他 <webview> 参数，例如 src URL。可以修改此对象以调整来宾页面的参数。

当 <webview> 的 web 内容正在附加到此 web 内容时发出。调用 event.preventDefault() 将销毁来宾页面。

此事件可用于在加载 <webview> 的 webContents 的 webPreferences 进行配置，并提供设置无法通过 <webview> 属性设置的设置的能力。

事件: 'did-attach-webview'

返回

• event Event
• webContents WebContents - <webview> 使用的来宾 web 内容。

当 <webview> 已附加到此 web 内容时发出。

事件: 'console-message'

返回

• details 事件<>
  • message 字符串 - 消息文本
  • level 字符串 - 消息严重性。可能的值包括 info, warning, error 和 debug。
  • lineNumber 整数 - 日志源中的行号
  • sourceId 字符串 - 日志源的 URL
  • frame WebFrameMain - 记录消息的框架
• level Integer 已弃用 - 日志级别，范围从 0 到 3。按顺序对应 verbose、info、warning 和 error。
• message string 已弃用 - 实际的控制台消息
• line Integer 已弃用 - 触发此控制台消息的源文件的行号
• sourceId string 已弃用

当关联的窗口记录控制台消息时发出。

Event: 'preload-error'

返回

• event Event
• preloadPath string
• error 错误

当预加载脚本 preloadPath 抛出未处理的异常 error 时发出。

Event: 'ipc-message'

返回

• event IpcMainEvent
• channel string
• ...args any[]

当渲染进程通过 ipcRenderer.send() 发送异步消息时发出。

另请参阅 webContents.ipc，它为响应来自此 WebContents 的 IPC 消息提供了一个类似于 IpcMain 的接口。

Event: 'ipc-message-sync'

返回

• event IpcMainEvent
• channel string
• ...args any[]

当渲染进程通过 ipcRenderer.sendSync() 发送同步消息时发出。

另请参阅 webContents.ipc，它为响应来自此 WebContents 的 IPC 消息提供了一个类似于 IpcMain 的接口。

Event: 'preferred-size-changed'

返回

• event Event
• preferredSize Size - 包含文档布局所需的最小尺寸——无需滚动。

当 WebContents 首选尺寸发生变化时发出。

只有当 webPreferences 中将 enablePreferredSizeMode 设置为 true 时，才会发出此事件。

Event: 'frame-created'

返回

• event Event
• details Object
  • frame WebFrameMain | null - 创建的框架。如果访问时框架已导航或销毁，则可能为 null。

当 mainFrame、<iframe> 或嵌套 <iframe> 在页面内加载时发出。

实例方法

contents.loadURL(url[, options])

• url string
• 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 将会 resolve，如果页面加载失败（参见 did-fail-load），则会 reject。已经附加了一个 noop rejection handler，可以避免未处理的 rejection 错误。如果现有页面具有 beforeUnload 处理程序，除非处理了 will-prevent-unload，否则将调用 did-fail-load。

在窗口中加载 url。url 必须包含协议前缀，例如 http:// 或 file://。如果应绕过 http 缓存，则使用 pragma 头部来实现。

const win = new BrowserWindow()
const options = { extraHeaders: 'pragma: no-cache\n' }
win.webContents.loadURL('https://github.com', options)

contents.loadFile(filePath[, options])

• filePath string
• options Object (可选)
  • query Record<string, string> (可选) - 传递给 url.format()。
  • search string (可选) - 传递给 url.format()。
  • hash string (可选) - 传递给 url.format()。

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

在窗口中加载给定的文件，filePath 应该是相对于应用程序根目录的 HTML 文件路径。例如，像这样的应用程序结构

| root
| - package.json
| - src
|   - main.js
|   - index.html

需要如下代码

const win = new BrowserWindow()
win.loadFile('src/index.html')

contents.downloadURL(url[, options])

• url string
• options Object (可选)
  • headers Record<string, string> (可选) - HTTP 请求头。

发起对 url 资源的下载，不进行导航。session 的 will-download 事件将被触发。

contents.getURL()

返回 string - 当前网页的 URL。

const { BrowserWindow } = require('electron')

const win = new BrowserWindow({ width: 800, height: 600 })
win.loadURL('https://github.com').then(() => {
  const currentURL = win.webContents.getURL()
  console.log(currentURL)
})

contents.getTitle()

返回 string - 当前网页的标题。

contents.isDestroyed()

返回 boolean - 网页是否已被销毁。

contents.close([opts])

• opts Object (可选)
  • waitForBeforeUnload boolean - 如果为 true，则在关闭页面之前触发 beforeunload 事件。如果页面阻止卸载，则 WebContents 将不会关闭。如果页面请求阻止卸载，将触发 will-prevent-unload。

关闭页面，就像 web 内容调用了 window.close() 一样。

如果页面成功关闭（即页面没有阻止卸载，或者 waitForBeforeUnload 为 false 或未指定），则 WebContents 将被销毁并且无法再使用。将发出 destroyed 事件。

contents.focus()

将焦点设置到网页。

contents.isFocused()

返回 boolean - 网页是否获得焦点。

contents.isLoading()

返回 boolean - 网页是否仍在加载资源。

contents.isLoadingMainFrame()

返回 boolean - 主框架（以及其中的 iframe 或框架）是否仍在加载。

contents.isWaitingForResponse()

返回 boolean - 网页是否正在等待页面的主要资源的第一个响应。

contents.stop()

停止任何待处理的导航。

contents.reload()

重新加载当前网页。

contents.reloadIgnoringCache()

重新加载当前页面并忽略缓存。

contents.canGoBack() 已弃用

历史

版本(s)	更改
None	API DEPRECATED

返回 boolean - 浏览器是否可以返回到上一个网页。

已弃用：应使用新的 contents.navigationHistory.canGoBack API。

contents.canGoForward() 已弃用

历史

版本(s)	更改
None	API DEPRECATED

返回 boolean - 浏览器是否可以前进到下一个网页。

已弃用：应使用新的 contents.navigationHistory.canGoForward API。

contents.canGoToOffset(offset) 已弃用

历史

版本(s)	更改
None	API DEPRECATED

• offset Integer

返回 boolean - 网页是否可以跳转到 offset。

已弃用：应使用新的 contents.navigationHistory.canGoToOffset API。

contents.clearHistory() 已弃用

历史

版本(s)	更改
None	API DEPRECATED

清除导航历史记录。

已弃用：应使用新的 contents.navigationHistory.clear API。

contents.goBack() 已弃用

历史

版本(s)	更改
None	API DEPRECATED

使浏览器返回一个网页。

已弃用：应使用新的 contents.navigationHistory.goBack API。

contents.goForward() 已弃用

历史

版本(s)	更改
None	API DEPRECATED

使浏览器前进一个网页。

已弃用：应使用新的 contents.navigationHistory.goForward API。

contents.goToIndex(index) 已弃用

历史

版本(s)	更改
None	API DEPRECATED

• index Integer

导航浏览器到指定的绝对网页索引。

已弃用：应使用新的 contents.navigationHistory.goToIndex API。

contents.goToOffset(offset) 已弃用

历史

版本(s)	更改
None	API DEPRECATED

• offset Integer

导航到相对于“当前条目”的指定偏移量。

已弃用：应使用新的 contents.navigationHistory.goToOffset API。

contents.isCrashed()

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

contents.forcefullyCrashRenderer()

强制终止当前托管此 webContents 的渲染器进程。这将导致发出 render-process-gone 事件，其中 reason=killed || reason=crashed。请注意，某些 webContents 共享渲染器进程，因此调用此方法也可能导致其他 webContents 的宿主进程崩溃。

在调用此方法后立即调用 reload() 将强制重新加载发生在新的进程中。当此进程不稳定或无法使用时，例如为了从 unresponsive 事件中恢复，应使用此方法。

const win = new BrowserWindow()

win.webContents.on('unresponsive', async () => {
  const { response } = await dialog.showMessageBox({
    message: 'App X has become unresponsive',
    title: 'Do you want to try forcefully reloading the app?',
    buttons: ['OK', 'Cancel'],
    cancelId: 1
  })
  if (response === 0) {
    win.webContents.forcefullyCrashRenderer()
    win.webContents.reload()
  }
})

contents.setUserAgent(userAgent)

• userAgent string

覆盖此网页的用户代理。

contents.getUserAgent()

返回 string - 此网页的用户代理。

contents.insertCSS(css[, options])

• css string
• options Object (可选)
  • cssOrigin 字符串 (可选) - 可以是 'user' 或 'author'。设置插入样式的 级联源。默认值为 'author'。

返回 Promise<string> - 一个 Promise，它解析为插入 CSS 的键，稍后可以使用 contents.removeInsertedCSS(key) 删除 CSS。

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

const win = new BrowserWindow()
win.webContents.on('did-finish-load', () => {
  win.webContents.insertCSS('html, body { background-color: #f00; }')
})

contents.removeInsertedCSS(key)

• key string

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

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

const win = new BrowserWindow()

win.webContents.on('did-finish-load', async () => {
  const key = await win.webContents.insertCSS('html, body { background-color: #f00; }')
  win.webContents.removeInsertedCSS(key)
})

contents.executeJavaScript(code[, userGesture])

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

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

在页面中执行 code。

在浏览器窗口中，某些 HTML API（如 requestFullScreen）只能由用户的手势调用。将 userGesture 设置为 true 将消除此限制。

代码执行将暂停，直到网页停止加载。

const win = new BrowserWindow()

win.webContents.executeJavaScript('fetch("https://jsonplaceholder.typicode.com/users/1").then(resp => resp.json())', true)
  .then((result) => {
    console.log(result) // Will be the JSON object from the fetch call
  })

contents.executeJavaScriptInIsolatedWorld(worldId, scripts[, userGesture])

• worldId 整数 - 在其中运行 javascript 的世界的 ID，0 是默认世界，999 是 Electron 的 contextIsolation 功能使用的世界。您可以在此处提供任何整数。
• scripts WebSource[]
• userGesture boolean (可选) - 默认为 false。

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

与 executeJavaScript 类似，但在隔离上下文中评估 scripts。

contents.setIgnoreMenuShortcuts(ignore)

• ignore boolean

当此 webContents 处于焦点状态时，忽略应用程序菜单快捷键。

contents.setWindowOpenHandler(handler)

• handler Function<WindowOpenHandlerResponse>

  • details Object
    • url 字符串 - 传递给 window.open() 的 URL 的 *解析* 版本。例如，使用 window.open('foo') 打开窗口将产生类似 https://the-origin/the/current/path/foo 的结果。
    • frameName 字符串 - 在 window.open() 中提供的窗口名称
    • features 字符串 - 传递给 window.open() 的以逗号分隔的窗口功能列表。
    • disposition string - 可以是 default、foreground-tab、background-tab、new-window 或 other。
    • referrer Referrer - 将传递给新窗口的引用者。根据引用者策略，Referer 标头可能不会发送。
    • postBody PostBody (可选) - 将与适当的标头一起发送到新窗口的 POST 数据。如果未发送 POST 数据，则该值为 null。仅当窗口由将 target=_blank 设置为 form 创建时才定义。

  返回 WindowOpenHandlerResponse - 当设置为 { action: 'deny' } 时，取消创建新窗口。{ action: 'allow' } 将允许创建新窗口。返回无法识别的值，例如 null、undefined 或没有识别的 'action' 值的对象，将导致控制台错误并产生与返回 {action: 'deny'} 相同的效果。

在渲染器请求创建新窗口之前调用，例如通过 window.open()、带有 target="_blank" 的链接、Shift+单击链接或提交带有 <form target="_blank"> 的表单。有关更多详细信息以及如何与 did-create-window 结合使用，请参阅 window.open()。

一个示例，展示如何自定义新的 BrowserWindow 创建过程，使其成为附加到主窗口的 BrowserView

const { BrowserView, BrowserWindow } = require('electron')

const mainWindow = new BrowserWindow()

mainWindow.webContents.setWindowOpenHandler((details) => {
  return {
    action: 'allow',
    createWindow: (options) => {
      const browserView = new BrowserView(options)
      mainWindow.addBrowserView(browserView)
      browserView.setBounds({ x: 0, y: 0, width: 640, height: 480 })
      return browserView.webContents
    }
  }
})

contents.setAudioMuted(muted)

• muted 布尔值

静音当前网页上的音频。

contents.isAudioMuted()

返回 boolean - 此页面是否已被静音。

contents.isCurrentlyAudible()

返回 boolean - 音频是否正在播放。

contents.setZoomFactor(factor)

• factor 双精度数 - 缩放因子；默认值为 1.0。

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

该因子必须大于 0.0。

contents.getZoomFactor()

返回 number - 当前缩放因子。

contents.setZoomLevel(level)

• level number - 缩放级别。

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

注意

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

contents.getZoomLevel()

返回 number - 当前缩放级别。

contents.setVisualZoomLevelLimits(minimumLevel, maximumLevel)

• minimumLevel number
• maximumLevel number

返回 Promise<void>

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

注意

Electron 默认禁用视觉缩放。要重新启用它，请调用

const win = new BrowserWindow()
win.webContents.setVisualZoomLevelLimits(1, 3)

contents.undo()

在网页中执行编辑命令 undo。

contents.redo()

在网页中执行编辑命令 redo。

contents.cut()

在网页中执行编辑命令 cut。

contents.copy()

在网页中执行编辑命令 copy。

contents.centerSelection()

在网页中将当前文本选择居中。

contents.copyImageAt(x, y)

• x Integer
• y Integer

将给定位置的图像复制到剪贴板。

contents.paste()

在网页中执行编辑命令 paste。

contents.pasteAndMatchStyle()

在网页中执行编辑命令 pasteAndMatchStyle。

contents.delete()

在网页中执行编辑命令 delete。

contents.selectAll()

在网页中执行编辑命令 selectAll。

contents.unselect()

在网页中执行编辑命令 unselect。

contents.scrollToTop()

滚动到当前 webContents 的顶部。

contents.scrollToBottom()

滚动到当前 webContents 的底部。

contents.adjustSelection(options)

• options Object
  • start 数字 (可选) - 将当前选择的起始索引偏移的量。
  • end 数字 (可选) - 将当前选择的结束索引偏移的量。

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

示例

const win = new BrowserWindow()

// Adjusts the beginning of the selection 1 letter forward,
// and the end of the selection 5 letters forward.
win.webContents.adjustSelection({ start: 1, end: 5 })

// Adjusts the beginning of the selection 2 letters forward,
// and the end of the selection 3 letters backward.
win.webContents.adjustSelection({ start: 2, end: -3 })

对于 win.webContents.adjustSelection({ start: 1, end: 5 }) 的调用

之前

之后

contents.replace(text)

• text string

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

contents.replaceMisspelling(text)

• text string

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

contents.insertText(text)

• text string

返回 Promise<void>

将 text 插入到焦点元素中。

contents.findInPage(text[, options])

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

返回 Integer - 请求用于请求的请求 ID。

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

contents.stopFindInPage(action)

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

停止 webContents 的任何 findInPage 请求，并使用提供的 action。

const win = new BrowserWindow()
win.webContents.on('found-in-page', (event, result) => {
  if (result.finalUpdate) win.webContents.stopFindInPage('clearSelection')
})

const requestId = win.webContents.findInPage('api')
console.log(requestId)

contents.capturePage([rect, opts])

• rect Rectangle (optional) - 要捕获的页面区域。
• opts Object (可选)
  • stayHidden boolean (optional) - 保持页面隐藏而不是可见。默认值为 false。
  • stayAwake boolean (optional) - 保持系统唤醒状态而不是允许其休眠。默认值为 false。

返回 Promise<NativeImage> - 解析为 NativeImage

捕获 rect 内页面的快照。省略 rect 将捕获整个可见页面。当其浏览器窗口隐藏且捕获器计数非零时，页面被认为是可见的。如果您希望页面保持隐藏状态，应确保将 stayHidden 设置为 true。

contents.isBeingCaptured()

返回 boolean - 是否正在捕获此页面。当捕获器计数大于 0 时，返回 true。

contents.getPrintersAsync()

获取系统打印机列表。

返回 Promise<PrinterInfo[]> - 解析为 PrinterInfo[]

contents.print([options], [callback])

• options Object (可选)
  • silent boolean (optional) - 不向用户询问打印设置。默认值为 false。
  • printBackground boolean (optional) - 打印网页的背景颜色和图像。默认值为 false。
  • deviceName string (optional) - 设置要使用的打印机设备名称。必须是系统定义的名称，而不是“友好”名称，例如 'Brother_QL_820NWB' 而不是 'Brother QL-820NWB'。
  • color boolean (optional) - 设置打印的网页是彩色还是灰度。默认值为 true。
  • margins Object (optional)
    • marginType string (optional) - 可以是 default、none、printableArea 或 custom。如果选择 custom，还需要指定 top、bottom、left 和 right。
    • top number (optional) - 打印网页的上边距，以像素为单位。
    • bottom number (optional) - 打印网页的下边距，以像素为单位。
    • left number (optional) - 打印网页的左边距，以像素为单位。
    • right number (optional) - 打印网页的右边距，以像素为单位。
  • landscape boolean (optional) - 网页是否应以横向模式打印。默认值为 false。
  • scaleFactor number (optional) - 网页的缩放比例。
  • pagesPerSheet number (optional) - 每张纸上打印的页数。
  • collate boolean (optional) - 网页是否应进行排序。
  • copies number (optional) - 要打印的网页份数。
  • pageRanges Object[] (optional) - 要打印的页面范围。在 macOS 上，仅会应用一个范围。
    • from number - 要打印的第一个页面的索引（从 0 开始）。
    • to number - 要打印的最后一个页面的索引（包括）（从 0 开始）。
  • duplexMode string (optional) - 设置打印网页的双面模式。可以是 simplex、shortEdge 或 longEdge。
  • dpi Record<string, number> (optional)
    • horizontal number (optional) - 水平 DPI。
    • vertical number (optional) - 垂直 DPI。
  • header string (optional) - 作为页面页眉打印的字符串。
  • footer string (optional) - 作为页面页脚打印的字符串。
  • pageSize string | Size (optional) - 指定打印文档的页面大小。可以是 A0、A1、A2、A3、A4、A5、A6、Legal、Letter、Tabloid 或包含 height 和 width 的对象。
• callback Function (optional)
  • success boolean - 指示打印调用是否成功。
  • failureReason string - 如果打印失败，则回调的错误描述。

当传递自定义 pageSize 时，Chromium 会尝试验证平台特定的 width_microns 和 height_microns 的最小值。宽度和高度必须都至少为 353 微米，但在某些操作系统上可能会更高。

打印窗口的网页。当 silent 设置为 true 时，如果 deviceName 为空，Electron 将选择系统的默认打印机以及默认的打印设置。

打印失败的一些可能的 failureReason 包括

• "无效的打印机设置"
• "打印作业已取消"
• "打印作业失败"

使用 page-break-before: always; CSS 样式强制打印到新页面。

示例用法

const win = new BrowserWindow()
const options = {
  silent: true,
  deviceName: 'My-Printer',
  pageRanges: [{
    from: 0,
    to: 1
  }]
}
win.webContents.print(options, (success, errorType) => {
  if (!success) console.log(errorType)
})

contents.printToPDF(options)

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

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

将窗口的网页打印为 PDF。

如果网页中使用 @page CSS at-rule，则会忽略 landscape。

webContents.printToPDF 的一个示例

const { app, BrowserWindow } = require('electron')

const fs = require('node:fs')
const os = require('node:os')
const path = require('node:path')

app.whenReady().then(() => {
  const win = new BrowserWindow()
  win.loadURL('https://github.com')

  win.webContents.on('did-finish-load', () => {
    // Use default printing options
    const pdfPath = path.join(os.homedir(), 'Desktop', 'temp.pdf')
    win.webContents.printToPDF({}).then(data => {
      fs.writeFile(pdfPath, data, (error) => {
        if (error) throw error
        console.log(`Wrote PDF successfully to ${pdfPath}`)
      })
    }).catch(error => {
      console.log(`Failed to write PDF to ${pdfPath}: `, error)
    })
  })
})

有关更多信息，请参阅 Page.printToPdf。

contents.addWorkSpace(path)

• path string

将指定的路径添加到 DevTools 工作区。必须在创建 DevTools 之后使用

const { BrowserWindow } = require('electron')

const win = new BrowserWindow()
win.webContents.on('devtools-opened', () => {
  win.webContents.addWorkSpace(__dirname)
})

contents.removeWorkSpace(path)

• path string

从 DevTools 工作区中删除指定的路径。

contents.setDevToolsWebContents(devToolsWebContents)

• devToolsWebContents WebContents

使用 devToolsWebContents 作为显示 DevTools 的目标 WebContents。

devToolsWebContents 必须没有进行任何导航，并且在调用之后不应用于其他目的。

默认情况下，Electron 通过创建具有本机视图的内部 WebContents 来管理 DevTools，开发人员对其控制非常有限。使用 setDevToolsWebContents 方法，开发人员可以使用任何 WebContents 在其中显示 DevTools，例如 BrowserWindow 或 WebContentsView。

请注意，关闭 DevTools 不会销毁 devToolsWebContents，调用者有责任手动销毁 devToolsWebContents。

在 BrowserWindow 中显示 DevTools 的示例

main.js

const { app, BrowserWindow } = require('electron')

let win = null
let devtools = null

app.whenReady().then(() => {
  win = new BrowserWindow()
  devtools = new BrowserWindow()
  win.loadURL('https://github.com')
  win.webContents.setDevToolsWebContents(devtools.webContents)
  win.webContents.openDevTools({ mode: 'detach' })
})

contents.openDevTools([options])

• options Object (可选)
  • mode string - 以指定的停靠状态打开 DevTools，可以是 left、right、bottom、undocked、detach。默认为上次使用的停靠状态。在 undocked 模式下可以停靠回去。在 detach 模式下则不能。
  • activate boolean (optional) - 是否将打开的 DevTools 窗口带到前台。默认值为 true。
  • title string (optional) - DevTools 窗口的标题（仅在 undocked 或 detach 模式下）。

打开 DevTools。

当 contents 是 <webview> 标签时，mode 默认会是 detach，显式传递一个空的 mode 可以强制使用上次使用的停靠状态。

在 Windows 上，如果启用了 Windows 控制叠加层，DevTools 将以 mode: 'detach' 的方式打开。

contents.closeDevTools()

关闭 DevTools 视图。

contents.isDevToolsOpened()

返回 boolean - 是否已打开 DevTools 视图。

contents.isDevToolsFocused()

返回 boolean - DevTools 视图是否获得焦点。

contents.getDevToolsTitle()

返回 string - DevTools 窗口的当前标题。只有在 DevTools 以 undocked 或 detach 模式打开时，此标题才可见。

contents.setDevToolsTitle(title)

• title string

将 DevTools 窗口的标题更改为 title。只有在 DevTools 以 undocked 或 detach 模式打开时，此标题才可见。

contents.toggleDevTools()

切换开发者工具。

contents.inspectElement(x, y)

• x Integer
• y Integer

开始检查位于 (x, y) 位置的元素。

contents.inspectSharedWorker()

打开共享 worker 上下文的开发者工具。

contents.inspectSharedWorkerById(workerId)

• workerId 字符串

根据其 ID 检查共享 worker。

contents.getAllSharedWorkers()

返回 SharedWorkerInfo[] - 关于所有共享 Worker 的信息。

contents.inspectServiceWorker()

打开服务 worker 上下文的开发者工具。

contents.send(channel, ...args)

• channel string
• ...args any[]

通过 channel 将异步消息发送到渲染进程，并附带参数。参数将使用 结构化克隆算法 进行序列化，就像 postMessage 一样，因此原型链将不会被包含。发送函数、Promise、Symbol、WeakMap 或 WeakSet 将抛出异常。

警告

发送非标准 JavaScript 类型，例如 DOM 对象或特殊的 Electron 对象，将抛出异常。

有关更多信息，请参阅 Electron 的 IPC 指南。

contents.sendToFrame(frameId, channel, ...args)

• frameId 整数 | [number, number] - 要发送到的框架的 ID，或者如果框架位于与主框架不同的进程中，则为 [processId, frameId] 对。
• channel string
• ...args any[]

通过 channel 将异步消息发送到渲染进程中的特定框架，并附带参数。参数将使用 结构化克隆算法 进行序列化，就像 postMessage 一样，因此原型链将不会被包含。发送函数、Promise、Symbol、WeakMap 或 WeakSet 将抛出异常。

注意： 发送非标准 JavaScript 类型，例如 DOM 对象或特殊的 Electron 对象，将抛出异常。

渲染进程可以通过使用 ipcRenderer 模块监听 channel 来处理消息。

如果您想获取给定渲染上下文的 frameId，您应该使用 webFrame.routingId 值。例如：

// In a renderer process
console.log('My frameId is:', require('electron').webFrame.routingId)

您还可以从主进程中的所有传入 IPC 消息中读取 frameId。

// In the main process
ipcMain.on('ping', (event) => {
  console.info('Message came from frameId:', event.frameId)
})

contents.postMessage(channel, message, [transfer])

• channel string
• message any
• transfer MessagePortMain[] (可选)

将消息发送到渲染进程，可以选择性地转移零个或多个 MessagePortMain 对象的所有权。

转移的 MessagePortMain 对象将在渲染进程中通过访问发出的事件的 ports 属性获得。当它们到达渲染器时，它们将是 native DOM MessagePort 对象。

例如

// Main process
const win = new BrowserWindow()
const { port1, port2 } = new MessageChannelMain()
win.webContents.postMessage('port', { message: 'hello' }, [port1])

// Renderer process
ipcRenderer.on('port', (e, msg) => {
  const [port] = e.ports
  // ...
})

contents.enableDeviceEmulation(parameters)

• parameters 对象
  • screenPosition 字符串 - 指定要模拟的屏幕类型（默认：desktop）
    • desktop - 桌面屏幕类型。
    • mobile - 移动屏幕类型。
  • screenSize Size - 设置模拟的屏幕尺寸（screenPosition == mobile）。
  • viewPosition Point - 将视图放置在屏幕上（screenPosition == mobile）（默认：{ x: 0, y: 0 }）。
  • deviceScaleFactor 整数 - 设置设备缩放因子（如果为零，则默认为原始设备缩放因子）（默认：0）。
  • viewSize Size - 设置模拟的视图尺寸（为空表示不覆盖）。
  • scale 浮点数 - 模拟视图在可用空间内的缩放比例（不在适应视图模式下）（默认：1）。

使用给定的参数启用设备模拟。

contents.disableDeviceEmulation()

禁用由 webContents.enableDeviceEmulation 启用的设备模拟。

contents.sendInputEvent(inputEvent)

• inputEvent MouseInputEvent | MouseWheelInputEvent | KeyboardInputEvent

将输入 event 发送到页面。

注意

包含 contents 的 BrowserWindow 需要获得焦点，sendInputEvent() 才能工作。

contents.beginFrameSubscription([onlyDirty ,]callback)

• onlyDirty 布尔值（可选）- 默认为 false。
• callback Function
  • image NativeImage
  • dirtyRect Rectangle

开始订阅演示事件和捕获的帧，当有演示事件时，将使用 callback(image, dirtyRect) 调用 callback。

image 是一个 NativeImage 实例，其中存储了捕获的帧。

dirtyRect 是一个包含 x, y, width, height 属性的对象，描述了页面中重新绘制的部分。如果将 onlyDirty 设置为 true，则 image 将仅包含重新绘制的区域。onlyDirty 默认为 false。

contents.endFrameSubscription()

结束订阅帧演示事件。

contents.startDrag(item)

• item 对象
  • file 字符串 - 要拖动的文件路径。
  • files 字符串[]（可选）- 要拖动的文件路径。（files 将覆盖 file 字段）
  • icon NativeImage | 字符串 - 在 macOS 上，图像必须非空。

将 item 设置为当前拖放操作的拖动项，file 是要拖动的文件绝对路径，icon 是拖动时鼠标下显示的图像。

contents.savePage(fullPath, saveType)

• fullPath 字符串 - 绝对文件路径。
• saveType 字符串 - 指定保存类型。
  • HTMLOnly - 仅保存页面的 HTML。
  • HTMLComplete - 保存完整的 HTML 页面。
  • MHTML - 将完整的 HTML 页面保存为 MHTML。

返回 Promise<void> - 如果页面已保存则 resolves。

const { BrowserWindow } = require('electron')

const win = new BrowserWindow()

win.loadURL('https://github.com')

win.webContents.on('did-finish-load', async () => {
  win.webContents.savePage('/tmp/test.html', 'HTMLComplete').then(() => {
    console.log('Page was saved successfully.')
  }).catch(err => {
    console.log(err)
  })
})

contents.showDefinitionForSelection() macOS

显示一个弹出式字典，搜索页面上选定的单词。

contents.isOffscreen()

返回 boolean - 指示是否启用了离屏渲染。

contents.startPainting()

如果启用了离屏渲染且尚未开始绘制，则开始绘制。

contents.stopPainting()

如果启用了离屏渲染且正在绘制，则停止绘制。

contents.isPainting()

返回 boolean - 如果启用了离屏渲染，则返回当前是否正在绘制。

contents.setFrameRate(fps)

• fps 整数

如果启用了离屏渲染，则将帧速率设置为指定的数字。仅接受 1 到 240 之间的值。

contents.getFrameRate()

返回 Integer - 如果启用了离屏渲染，则返回当前的帧速率。

contents.invalidate()

安排重绘包含此 Web 内容的窗口。

如果启用了离屏渲染，则使帧失效并通过 'paint' 事件生成一个新帧。

contents.getWebRTCIPHandlingPolicy()

返回 string - 返回 WebRTC IP 处理策略。

contents.setWebRTCIPHandlingPolicy(policy)

• policy 字符串 - 指定 WebRTC IP 处理策略。
  • default - 暴露用户的公共和本地 IP。这是默认行为。当使用此策略时，WebRTC 有权枚举所有接口并将它们绑定以发现公共接口。
  • default_public_interface_only - 暴露用户的公共 IP，但不暴露用户的本地 IP。当使用此策略时，WebRTC 应该只使用 http 使用的默认路由。这不会暴露任何本地地址。
  • default_public_and_private_interfaces - 暴露用户的公共和本地 IP。当使用此策略时，WebRTC 应该只使用 http 使用的默认路由。这也会暴露相关的默认私有地址。默认路由是多宿端点在操作系统上选择的路由。
  • disable_non_proxied_udp - 不暴露公共或本地 IP。当使用此策略时，WebRTC 应该只使用 TCP 与对等方或服务器联系，除非代理服务器支持 UDP。

设置 WebRTC IP 处理策略允许您控制通过 WebRTC 暴露哪些 IP。有关更多详细信息，请参阅 BrowserLeaks。

contents.getWebRTCUDPPortRange()

返回 Object

• min 整数 - WebRTC 应该使用的最小 UDP 端口号。
• max 整数 - WebRTC 应该使用的最大 UDP 端口号。

默认情况下，此值为 { min: 0, max: 0 }，这将不会对 udp 端口范围施加任何限制。

contents.setWebRTCUDPPortRange(udpPortRange)

• udpPortRange 对象
  • min 整数 - WebRTC 应该使用的最小 UDP 端口号。
  • max 整数 - WebRTC 应该使用的最大 UDP 端口号。

设置 WebRTC UDP 端口范围允许您限制 WebRTC 使用的 udp 端口范围。默认情况下，端口范围不受限制。

注意

要重置为不受限制的端口范围，应将此值设置为 { min: 0, max: 0 }。

contents.getMediaSourceId(requestWebContents)

• requestWebContents WebContents - 将注册 ID 的 Web 内容。

返回 string - WebContents 流的标识符。可以使用 chromeMediaSource 为 tab 的 navigator.mediaDevices.getUserMedia 使用此标识符。该标识符仅限于注册它的 Web 内容，并且仅在 10 秒内有效。

contents.getOSProcessId()

返回 Integer - 关联渲染进程的操作系统 pid。

contents.getProcessId()

返回 Integer - 关联渲染器的 Chromium 内部 pid。可以与通过帧特定导航事件（例如 did-frame-navigate）传递的 frameProcessId 进行比较

contents.takeHeapSnapshot(filePath)

• filePath 字符串 - 输出文件的路径。

返回 Promise<void> - 指示是否已成功创建快照。

获取 V8 堆快照并将其保存到 filePath。

contents.getBackgroundThrottling()

返回 boolean - 此 WebContents 是否会限制页面变为后台时动画和计时器。这也会影响页面可见性 API。

contents.setBackgroundThrottling(allowed)

历史

版本(s)	更改
None	将 WebContents.backgroundThrottling 设置为 false 会影响主机 BrowserWindow 中的所有 WebContents

• allowed 布尔值

控制此 WebContents 是否会限制页面变为后台时动画和计时器。这也会影响页面可见性 API。

contents.getType()

返回 string - Web 内容的类型。可以是 backgroundPage、window、browserView、remote、webview 或 offscreen。

contents.setImageAnimationPolicy(policy)

• policy 字符串 - 可以是 animate、animateOnce 或 noAnimation。

设置此 WebContents 的图像动画策略。该策略仅影响新图像，当前正在动画的现有图像不受影响。这是 Chromium 中的一个已知限制，可以通过 img.src = img.src 强制重新计算图像动画，这将不会产生任何网络流量，但会更新动画策略。

这对应于 Chromium 中的 animationPolicy 可访问性功能。

实例属性

contents.ipc 只读

一个 IpcMain，其范围仅限于从此 WebContents 发送的 IPC 消息。

使用 ipcRenderer.send、ipcRenderer.sendSync 或 ipcRenderer.postMessage 发送的 IPC 消息将按以下顺序传递

1. contents.on('ipc-message')
2. contents.mainFrame.on(channel)
3. contents.ipc.on(channel)
4. ipcMain.on(channel)

使用 invoke 注册的处理程序将按以下顺序进行检查。将调用第一个定义的处理程序，其余将被忽略。

1. contents.mainFrame.handle(channel)
2. contents.handle(channel)
3. ipcMain.handle(channel)

在 WebContents 上注册的处理程序或事件侦听器将接收来自任何帧（包括子帧）发送的 IPC 消息。在大多数情况下，只有主帧可以发送 IPC 消息。但是，如果启用了 nodeIntegrationInSubFrames 选项，则子帧也可以发送 IPC 消息。在这种情况下，处理程序应检查 IPC 事件的 senderFrame 属性，以确保消息来自预期的帧。或者，使用 WebFrameMain.ipc 接口直接在适当的帧上注册处理程序。

contents.audioMuted

一个 boolean 属性，用于确定此页面是否已静音。

contents.userAgent

一个 string 属性，用于确定此网页的用户代理。

contents.zoomLevel

一个 number 属性，用于确定此 Web 内容的缩放级别。

原始大小为 0，每个增量或减量表示相对于默认限制的 20% 放大或缩小，分别为原始大小的 300% 和 50%。此公式为 scale := 1.2 ^ level。

contents.zoomFactor

一个 number 属性，用于确定此 Web 内容的缩放因子。

缩放因子是缩放百分比除以 100，因此 300% = 3.0。

contents.frameRate

一个 Integer 属性，用于将 Web 内容的帧速率设置为指定的数字。仅接受 1 到 240 之间的值。

仅当启用离屏渲染时才适用。

contents.id 只读

一个 Integer，表示此 WebContents 的唯一 ID。每个 ID 在整个 Electron 应用程序的所有 WebContents 实例中都是唯一的。

contents.session 只读

用于此 webContents 的 Session。

contents.navigationHistory 只读

用于此 webContents 的 NavigationHistory。

contents.hostWebContents 只读

一个 WebContents 实例，它可能拥有此 WebContents。

contents.devToolsWebContents 只读

一个 WebContents | null 属性，表示与给定 WebContents 关联的 DevTools WebContents。

注意

用户不应存储此对象，因为它可能在关闭 DevTools 时变为 null。

contents.debugger 只读

此 webContents 的 Debugger 实例。

contents.backgroundThrottling

历史

版本(s)	更改
None	将 WebContents.backgroundThrottling 设置为 false 会影响主机 BrowserWindow 中的所有 WebContents

一个 boolean 属性，用于确定当页面变为后台时，此 WebContents 是否会限制动画和计时器。 这也会影响页面可见性 API。

contents.mainFrame 只读

一个 WebFrameMain 属性，表示页面框架层次结构的顶级框架。

contents.opener 只读

一个 WebFrameMain | null 属性，表示打开此 WebContents 的框架，无论是通过 open() 还是通过导航具有 target 属性的链接。

contents.focusedFrame 只读

一个 WebFrameMain | null 属性，表示此 WebContents 中当前聚焦的框架。 可以是顶级框架、内部 <iframe>，或者如果没有聚焦任何内容则为 null。