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 导航到另一个页面时（与 页面内导航 相反），将触发以下事件。

• 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 事件仅在 mainFrame 导航时触发。如果要观察 <iframe> 中的导航，请使用 will-frame-navigate 和 did-frame-navigate 事件。

方法

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

const { webContents } = require('electron')

console.log(webContents)

webContents.getAllWebContents()

返回 WebContents[] - 所有 WebContents 实例的数组。这包括所有窗口、webview、已打开的 DevTools 和 DevTools 扩展背景页面的 WebContents。

webContents.getFocusedWebContents()

返回 WebContents | null - 此应用程序中具有焦点的 WebContents，否则返回 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 - 与 WebContents 实例关联的 Chrome DevTools Protocol TargetID。

返回 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 数组。

当页面收到图标 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 (可选) - 将与适当设置的标头一起发送到新窗口的帖子数据。如果没有要发送的帖子数据，则值为 null。仅当窗口是由设置了 target=_blank 的表单创建时才定义。
  • 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 boolean - 导航是否在未更改文档的情况下发生。同文档导航的示例包括引用片段导航、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 boolean - 导航是否在未更改文档的情况下发生。同文档导航的示例包括引用片段导航、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 boolean - 导航是否在未更改文档的情况下发生。同文档导航的示例包括引用片段导航、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 Integer - 非 HTTP 导航为 -1
• httpStatusText string - 非 HTTP 导航为空

主框架导航完成时发出。

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

事件：'did-frame-navigate'

返回

• event Event
• 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'

返回

• 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 Object - 输入属性。
  • type string - keyUp 或 keyDown。
  • key string - 等同于 KeyboardEvent.key。
  • code string - 等同于 KeyboardEvent.code。
  • isAutoRepeat boolean - 等同于 KeyboardEvent.repeat。
  • isComposing boolean - 等同于 KeyboardEvent.isComposing。
  • shift boolean - 等同于 KeyboardEvent.shiftKey。
  • control boolean - 等同于 KeyboardEvent.controlKey。
  • alt boolean - 等同于 KeyboardEvent.altKey。
  • meta boolean - 等同于 KeyboardEvent.metaKey。
  • location number - 等同于 KeyboardEvent.location。
  • modifiers string[] - 请参阅 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 string - 可以是 in 或 out。

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

事件：'blur'

WebContents 失去焦点时发出。

事件：'focus'

WebContents 获得焦点时发出。

请注意，在 macOS 上，具有焦点意味着 WebContents 是窗口的 first responder，因此在窗口之间切换焦点不会触发 WebContents 的 focus 和 blur 事件，因为每个窗口的 first responder 都不会改变。

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

事件：'devtools-open-url'

返回

• event Event
• url string - 单击或选择的链接的 URL。

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

事件：'devtools-search-query'

返回

• event Event
• query string - 要搜索的文本。

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

事件：'devtools-opened'

DevTools 打开时发出。

事件：'devtools-closed'

DevTools 关闭时发出。

事件：'devtools-focused'

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

事件：'certificate-error'

返回

• event Event
• url string
• error string - 错误代码。
• certificate Certificate
• callback Function
  • isTrusted boolean - 指示证书是否可以被认为是受信任的。
• 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 Object
  • 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 Object
  • requestId Integer
  • activeMatchOrdinal Integer - 活动匹配项的序号。
  • matches Integer - 匹配项数量。
  • selectionArea Rectangle - 第一个匹配区域的坐标。
  • finalUpdate boolean

为 webContents.findInPage 请求提供了结果时发出。

事件：'media-started-playing'

媒体开始播放时发出。

事件：'media-paused'

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

事件：'audio-state-changed'

返回

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

媒体变得可听或不可听时发出。

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

返回

• event Event
• color (string | null) - 主题颜色格式为 '#rrggbb'。如果未设置主题颜色，则为 null。

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

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

事件：'update-target-url'

返回

• event Event
• url string

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

事件：'cursor-changed'

返回

• event Event
• type string
• 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 Object
  • x Integer - x 坐标。
  • y Integer - y 坐标。
  • frame WebFrameMain | null - 调用上下文菜单的框架。如果访问时框架已导航或已销毁，则可能为 null。
  • 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 - 渲染器是否能够富文本编辑。

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

事件：'select-bluetooth-device'

返回

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

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

如果未为此事件添加事件监听器，所有蓝牙请求都将被取消。

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

由于蓝牙的特性，调用 navigator.bluetooth.requestDevice 时扫描设备可能需要一些时间，并且会导致 select-bluetooth-device 多次触发，直到 callback 使用设备 ID 或空字符串（用于取消请求）进行调用。

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 (可选) 实验性 - 帧的 GPU 共享纹理，当 webPreferences.offscreen.useSharedTexture 为 true 时。
• 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 - 将用于 guest 页面的 WebPreferences。可以修改此对象以调整 guest 页面的首选项。
• params Record<string, string> - 其他 <webview> 参数，例如 src URL。可以修改此对象以调整 guest 页面的参数。

当 <webview> 的 WebContents 正在附加到此 WebContents 时发出。调用 event.preventDefault() 将销毁 guest 页面。

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

事件：'did-attach-webview'

返回

• event Event
• webContents WebContents - <webview> 使用的 guest WebContents。

<webview> 已附加到此 WebContents 时发出。

事件： 'console-message'

返回

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

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

事件：'preload-error'

返回

• event Event
• preloadPath string
• error 错误

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

事件：'ipc-message'

返回

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

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

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

事件：'ipc-message-sync'

返回

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

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

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

事件：'preferred-size-changed'

返回

• event Event
• preferredSize Size - 容纳文档布局所需的最小尺寸，无需滚动。

WebContents 的首选大小已更改时发出。

此事件仅在 webPreferences 中将 enablePreferredSizeMode 设置为 true 时发出。

事件：'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 (可选) - 由 data URL 加载的文件的基本 URL（带尾部路径分隔符）。仅当指定的 url 是 data URL 且需要加载其他文件时才需要。

返回 Promise<void> - 当页面完成加载时（请参阅 did-finish-load），Promise 将解析；如果页面加载失败（请参阅 did-fail-load），则拒绝。已附加了一个 noop 拒绝处理程序，避免了未处理的拒绝错误。

在窗口中加载 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 将解析；如果页面加载失败（请参阅 did-fail-load），则拒绝。

在窗口中加载指定的文件，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 事件。

关闭页面，如同 WebContents 调用了 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 string (可选) - 可以是 '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 Integer - 运行 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 string - 传递给 window.open() 的 URL 的 *解析后* 的版本。例如，使用 window.open('foo') 打开一个窗口将得到类似 https://the-origin/the/current/path/foo 的结果。
    • frameName string - window.open() 中提供的窗口名称
    • features string - 传递给 window.open() 的窗口功能的逗号分隔列表。
    • disposition string - 可以是 default、foreground-tab、background-tab、new-window 或 other。
    • referrer Referrer - 将传递给新窗口的引用者。根据引用者策略，这可能导致发送 Referer 标头，也可能不发送。
    • postBody PostBody (可选) - 将与适当设置的标头一起发送到新窗口的帖子数据。如果没有要发送的帖子数据，则值为 null。仅当窗口是由设置了 target=_blank 的表单创建时才定义。

  返回 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 boolean

静音当前网页的音频。

contents.isAudioMuted()

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

contents.isCurrentlyAudible()

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

contents.setZoomFactor(factor)

• factor Double - 缩放因子；默认为 1.0。

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

因子必须大于 0.0。

contents.getZoomFactor()

返回 number - 当前缩放因子。

contents.setZoomLevel(level)

• level number - 缩放级别。

将缩放级别更改为指定的级别。原始大小为 0，每增加或减少一个级别，表示缩放比原始大小大或小 20%，分别在 300% 和 50% 的默认限制范围内。公式为 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 Number (可选) - 移动当前选区起始索引的量。
  • end Number (可选) - 移动当前选区结束索引的量。

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

示例

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 (可选) - 是否向前或向后搜索，默认为 true。
  • findNext boolean (可选) - 是否以此请求开始新的文本查找会话。对于初始请求应为 true，对于后续请求应为 false。默认为 false。
  • matchCase boolean (可选) - 搜索是否区分大小写，默认为 false。

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

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

contents.stopFindInPage(action)

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

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

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 (可选) - 要捕获的页面区域。
• opts Object (可选)
  • stayHidden boolean (可选) - 保持页面隐藏而不是可见。默认为 false。
  • stayAwake boolean (可选) - 保持系统清醒而不是允许其睡眠。默认为 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 布尔值 (可选) - 不向用户询问打印设置。默认为 false。
  • printBackground 布尔值 (可选) - 打印网页的背景颜色和图像。默认为 false。
  • deviceName 字符串 (可选) - 设置要使用的打印机设备名称。必须是系统定义的名称，而不是“友好”名称，例如 'Brother_QL_820NWB' 而不是 'Brother QL-820NWB'。
  • color 布尔值 (可选) - 设置打印的网页是彩色还是灰度。默认为 true。
  • margins 对象 (可选)
    • marginType 字符串 (可选) - 可以是 default、none、printableArea 或 custom。如果选择 custom，您还需要指定 top、bottom、left 和 right。
    • top 数字 (可选) - 打印的网页的顶部边距，以像素为单位。
    • bottom 数字 (可选) - 打印的网页的底部边距，以像素为单位。
    • left 数字 (可选) - 打印的网页的左边距，以像素为单位。
    • right 数字 (可选) - 打印的网页的右边距，以像素为单位。
  • landscape 布尔值 (可选) - 网页是否应以横向模式打印。默认为 false。
  • scaleFactor 数字 (可选) - 网页的缩放因子。
  • pagesPerSheet 数字 (可选) - 每张纸打印的页数。
  • collate 布尔值 (可选) - 网页是否应按顺序打印。
  • copies 数字 (可选) - 要打印的网页副本数量。
  • pageRanges 对象[] (可选) - 要打印的页面范围。在 macOS 上，只有一个范围有效。
    • from 数字 - 要打印的第一页的索引（从 0 开始）。
    • to 数字 - 要打印的最后一页的索引（包含）（从 0 开始）。
  • duplexMode 字符串 (可选) - 设置打印网页的装订模式。可以是 simplex（单面）、shortEdge（短边装订）或 longEdge（长边装订）。
  • dpi 记录<字符串, 数字> (可选)
    • horizontal 数字 (可选) - 水平 DPI。
    • vertical 数字 (可选) - 垂直 DPI。
  • header 字符串 (可选) - 作为页面页眉打印的字符串。
  • footer 字符串 (可选) - 作为页面页脚打印的字符串。
  • pageSize 字符串 | Size (可选) - 指定打印文档的页面大小。可以是 A0、A1、A2、A3、A4、A5、A6、Legal、Letter、Tabloid 或包含 height 和 width 的对象。
• callback 函数 (可选)
  • success 布尔值 - 指示打印调用的成功状态。
  • failureReason 字符串 - 如果打印失败，回调的错误描述。

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

请注意，关闭 DevTools 不会销毁 devToolsWebContents，销毁 devToolsWebContents 是调用者的责任。

在 <webview> 标签中显示 DevTools 的示例

<html>
<head>
  <style type="text/css">
    * { margin: 0; }
    #browser { height: 70%; }
    #devtools { height: 30%; }
  </style>
</head>
<body>
  <webview id="browser" src="https://github.com"></webview>
  <webview id="devtools" src="about:blank"></webview>
  <script>
    const { ipcRenderer } = require('electron')
    const emittedOnce = (element, eventName) => new Promise(resolve => {
      element.addEventListener(eventName, event => resolve(event), { once: true })
    })
    const browserView = document.getElementById('browser')
    const devtoolsView = document.getElementById('devtools')
    const browserReady = emittedOnce(browserView, 'dom-ready')
    const devtoolsReady = emittedOnce(devtoolsView, 'dom-ready')
    Promise.all([browserReady, devtoolsReady]).then(() => {
      const targetId = browserView.getWebContentsId()
      const devtoolsId = devtoolsView.getWebContentsId()
      ipcRenderer.send('open-devtools', targetId, devtoolsId)
    })
  </script>
</body>
</html>

// Main process
const { ipcMain, webContents } = require('electron')

ipcMain.on('open-devtools', (event, targetContentsId, devtoolsContentsId) => {
  const target = webContents.fromId(targetContentsId)
  const devtools = webContents.fromId(devtoolsContentsId)
  target.setDevToolsWebContents(devtools)
  target.openDevTools()
})

在 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 字符串 - 以指定的停靠状态打开 DevTools，可以是 left（左侧）、right（右侧）、bottom（底部）、undocked（未停靠）或 detach（分离）。默认为上次使用的停靠状态。在 undocked 模式下可以重新停靠。在 detach 模式下则不能。
  • activate 布尔值 (可选) - 是否将打开的 DevTools 窗口带到前台。默认为 true。
  • title 字符串 (可选) - 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()

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

contents.inspectSharedWorkerById(workerId)

• workerId 字符串

根据 ID 检查共享工作者。

contents.getAllSharedWorkers()

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

contents.inspectServiceWorker()

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

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 整数 | [数字, 数字] - 发送到的 frame 的 ID，或者如果是不同进程中的 frame，则为 [processId, frameId] 对。
• channel string
• ...args any[]

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

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

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

如果您想获取给定渲染器上下文的 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 属性在渲染进程中获得。当它们到达渲染进程时，将是原生的 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。

注意

包含该内容的 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> - 如果页面已保存，则解析。

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()

计划重绘该 webContents 所在的窗口。

如果离屏渲染已启用，则使帧无效并生成新的帧（通过 'paint' 事件）。

contents.getWebRTCIPHandlingPolicy()

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

contents.setWebRTCIPHandlingPolicy(policy)

• policy 字符串 - 指定 WebRTC IP 处理策略。
  • default - 公开用户的公共 IP 和本地 IP。这是默认行为。使用此策略时，WebRTC 有权枚举所有接口并绑定它们以发现公共接口。
  • default_public_interface_only - 公开用户的公共 IP，但不公开用户的本地 IP。使用此策略时，WebRTC 应仅使用 http 的默认路由。这不会公开任何本地地址。
  • default_public_and_private_interfaces - 公开用户的公共 IP 和本地 IP。使用此策略时，WebRTC 应仅使用 http 的默认路由。这还会公开关联的默认私有地址。默认路由是多宿主终端上由操作系统选择的路由。
  • disable_non_proxied_udp - 不公开公共 IP 或本地 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 contents。

返回 string - WebContents 流的标识符。此标识符可与 navigator.mediaDevices.getUserMedia 一起使用，其中 chromeMediaSource 为 tab。此标识符仅限于注册到的 web contents，并且仅在 10 秒内有效。

contents.getOSProcessId()

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

contents.getProcessId()

返回 Integer - 相关渲染进程的 Chromium 内部 pid。可以与 frame 特定导航事件（例如 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 - webContent 的类型。可以是 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 上注册的处理程序或事件侦听器将接收从任何 frame 发送的 IPC 消息，包括子 frame。在大多数情况下，只有主 frame 可以发送 IPC 消息。但是，如果启用了 nodeIntegrationInSubFrames 选项，子 frame 也可以发送 IPC 消息。在这种情况下，处理程序应检查 IPC 事件的 senderFrame 属性，以确保消息来自预期的 frame。或者，可以直接使用 WebFrameMain.ipc 接口在相应的 frame 上注册处理程序。

contents.audioMuted

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

contents.userAgent

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

contents.zoomLevel

一个 number 属性，用于确定此 web contents 的缩放级别。

原始大小为 0，每次向上或向下增加表示分别放大或缩小 20%，直至达到 300% 和 50% 的原始尺寸的限制。其公式为 scale := 1.2 ^ level。

contents.zoomFactor

一个 number 属性，用于确定此 web contents 的缩放因子。

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

contents.frameRate

一个 Integer 属性，将 web contents 的帧率设置为指定的数字。仅接受 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 属性，表示页面 frame 层次结构的顶层 frame。

contents.opener 只读

一个 WebFrameMain | null 属性，表示打开此 WebContents 的 frame，该 frame 通过 open() 或通过导航带有 target 属性的链接打开。

contents.focusedFrame 只读

一个 WebFrameMain | null 属性，表示此 WebContents 中当前获得焦点的 frame。可以是顶层 frame、内部 <iframe>，如果没有任何 frame 获得焦点，则为 null。