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

框架导航

当 mainFrame 导航时，will-navigate 和 did-navigate 事件才会触发。如果您还想观察 <iframe> 中的导航，请使用 will-frame-navigate 和 did-frame-navigate 事件。

方法

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

const { webContents } = require('electron')
console.log(webContents)

webContents.getAllWebContents()

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

webContents.getFocusedWebContents()

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

webContents.fromId(id)

• id 整数

返回 WebContents | undefined - 具有给定 ID 的 WebContents 实例，如果不存在与给定 ID 关联的 WebContents，则返回 undefined。

webContents.fromFrame(frame)

• frame WebFrameMain

返回 WebContents | undefined - 具有给定 WebFrameMain 的 WebContents 实例，如果不存在与给定 WebFrameMain 关联的 WebContents，则返回 undefined。

webContents.fromDevToolsTargetId(targetId)

• targetId 字符串 - 与 WebContents 实例关联的 Chrome DevTools 协议 TargetID。

返回 WebContents | undefined - 具有给定 TargetID 的 WebContents 实例，如果不存在与给定 TargetID 关联的 WebContents，则返回 undefined。

与 Chrome DevTools 协议 通信时，根据其分配的 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 事件
• errorCode 整数
• errorDescription 字符串
• validatedURL 字符串
• isMainFrame 布尔值
• frameProcessId 整数
• frameRoutingId 整数

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

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

返回

• event 事件
• errorCode 整数
• errorDescription 字符串
• validatedURL 字符串
• isMainFrame 布尔值
• frameProcessId 整数
• frameRoutingId 整数

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

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

返回

• event 事件
• isMainFrame 布尔值
• frameProcessId 整数
• frameRoutingId 整数

框架完成导航后发出。

事件: 'did-start-loading'

对应于标签页的微调器开始旋转的时间点。

事件: 'did-stop-loading'

对应于标签页的微调器停止旋转的时间点。

事件: 'dom-ready'

顶级框架中的文档加载完成后发出。

事件: 'page-title-updated'

返回

• event 事件
• title 字符串
• explicitSet 布尔值

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

事件: 'page-favicon-updated'

返回

• event 事件
• favicons 字符串[] - URL 数组。

页面收到收藏夹图标 URL 时发出。

事件: 'content-bounds-updated'

返回

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

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

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

事件: 'did-create-window'

返回

• window BrowserWindow
• details 对象
  • url 字符串 - 创建窗口的 URL。
  • frameName 字符串 - 在 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 Event<>
  • url string - 框架要导航到的 URL。
  • isSameDocument boolean - 此事件不会针对使用 window.history api 和引用片段导航的相同文档导航触发。此属性对于此事件始终设置为 false。
  • isMainFrame boolean - 如果导航发生在主框架中，则为 true。
  • frame WebFrameMain - 要导航的框架。
  • initiator WebFrameMain (可选) - 启动导航的框架，可以是父框架（例如，通过带有框架名称的 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 Event<>
  • url string - 框架要导航到的 URL。
  • isSameDocument boolean - 此事件不会针对使用 window.history api 和引用片段导航的相同文档导航触发。此属性对于此事件始终设置为 false。
  • isMainFrame boolean - 如果导航发生在主框架中，则为 true。
  • frame WebFrameMain - 要导航的框架。
  • initiator WebFrameMain (可选) - 启动导航的框架，可以是父框架（例如，通过带有框架名称的 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 Event<>
  • url string - 框架要导航到的 URL。
  • isSameDocument boolean - 导航是否在不更改文档的情况下发生的。相同文档导航的示例包括引用片段导航、pushState/replaceState 和同一页面历史记录导航。
  • isMainFrame boolean - 如果导航发生在主框架中，则为 true。
  • frame WebFrameMain - 要导航的框架。
  • initiator WebFrameMain (可选) - 启动导航的框架，可以是父框架（例如，通过带有框架名称的 window.open），如果导航不是由框架启动，则为 null。如果启动框架在事件发出之前被删除，这也可能为 null。
• url string 已弃用
• isInPlace boolean 已弃用
• isMainFrame boolean 已弃用
• frameProcessId Integer 已弃用
• frameRoutingId Integer 已弃用

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

事件: 'will-redirect'

返回

• details Event<>
  • url string - 框架要导航到的 URL。
  • isSameDocument boolean - 导航是否在不更改文档的情况下发生的。相同文档导航的示例包括引用片段导航、pushState/replaceState 和同一页面历史记录导航。
  • isMainFrame boolean - 如果导航发生在主框架中，则为 true。
  • frame WebFrameMain - 要导航的框架。
  • initiator WebFrameMain (可选) - 启动导航的框架，可以是父框架（例如，通过带有框架名称的 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 Event<>
  • url string - 框架要导航到的 URL。
  • isSameDocument boolean - 导航是否在不更改文档的情况下发生的。相同文档导航的示例包括引用片段导航、pushState/replaceState 和同一页面历史记录导航。
  • isMainFrame boolean - 如果导航发生在主框架中，则为 true。
  • frame WebFrameMain - 要导航的框架。
  • initiator WebFrameMain (可选) - 启动导航的框架，可以是父框架（例如，通过带有框架名称的 window.open），如果导航不是由框架启动，则为 null。如果启动框架在事件发出之前被删除，这也可能为 null。
• url string 已弃用
• isInPlace boolean 已弃用
• isMainFrame boolean 已弃用
• frameProcessId Integer 已弃用
• frameRoutingId Integer 已弃用

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

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

事件: 'did-navigate'

返回

• event 事件
• url string
• httpResponseCode Integer - 非 HTTP 导航的 -1
• httpStatusText string - 非 HTTP 导航的空

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

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

事件: 'did-frame-navigate'

返回

• event 事件
• url string
• httpResponseCode Integer - 非 HTTP 导航的 -1
• httpStatusText string - 非 HTTP 导航的空,
• isMainFrame 布尔值
• frameProcessId 整数
• frameRoutingId 整数

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

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

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

返回

• event 事件
• url string
• isMainFrame 布尔值
• frameProcessId 整数
• frameRoutingId 整数

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

当页面内导航发生时，页面 URL 会发生变化，但不会导致导航到页面之外。发生这种情况的示例包括单击锚链接或触发 DOM hashchange 事件时。

事件: 'will-prevent-unload'

返回

• 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 事件
• details RenderProcessGoneDetails

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

事件: 'unresponsive'

当网页变得无响应时发出。

事件: 'responsive'

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

事件: 'plugin-crashed'

返回

• event 事件
• name string
• version string

当插件进程崩溃时发出。

事件: 'destroyed'

当 webContents 被销毁时发出。

事件: 'input-event'

返回

• event 事件
• inputEvent InputEvent

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

事件: 'before-input-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 { BrowserWindow } = require('electron')

const win = new BrowserWindow({ width: 800, height: 600 })

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

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

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

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

当窗口退出由 HTML API 触发的全屏状态时发出。

事件: 'zoom-changed'

返回

• event 事件
• zoomDirection string - 可以是 in 或 out。

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

事件: 'blur'

当 WebContents 失去焦点时发出。

事件: 'focus'

当 WebContents 获得焦点时发出。

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

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

事件: 'devtools-open-url'

返回

• event 事件
• url 字符串 - 被点击或选择的链接的 URL。

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

事件: 'devtools-search-query'

返回

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

当在它的上下文菜单中选择“搜索”时触发。

事件: 'devtools-opened'

当 DevTools 打开时触发。

事件: 'devtools-closed'

当 DevTools 关闭时触发。

事件: 'devtools-focused'

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

事件: 'certificate-error'

返回

• event 事件
• url string
• error 字符串 - 错误代码。
• certificate 证书
• callback 函数
  • isTrusted 布尔值 - 指示证书是否可以被视为可信。
• isMainFrame 布尔值

当无法验证 url 的 certificate 时触发。

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

事件: 'select-client-certificate'

返回

• event 事件
• url URL
• certificateList 证书[]
• callback 函数
  • certificate 证书 - 必须是给定列表中的一个证书。

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

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

事件: 'login'

返回

• event 事件
• authenticationResponseDetails 对象
  • url URL
• authInfo 对象
  • isProxy 布尔值
  • scheme 字符串
  • host 字符串
  • port 整数
  • realm 字符串
• callback 函数
  • username 字符串（可选）
  • password 字符串（可选）

当 webContents 想要进行基本身份验证时触发。

使用方法与 app 的 login 事件 相同。

事件: 'found-in-page'

返回

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

当 webContents.findInPage 请求有结果时触发。

事件: 'media-started-playing'

当媒体开始播放时触发。

事件: 'media-paused'

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

事件: 'audio-state-changed'

返回

• event 事件<>
  • audible 布尔值 - 如果一个或多个帧或子 webContents 正在发出音频，则为真。

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

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

返回

• event 事件
• color (字符串 | null) - 主题颜色格式为 '#rrggbb'。当没有设置主题颜色时为 null。

当页面的主题颜色发生变化时触发。这通常是由于遇到了 meta 标签。

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

事件: 'update-target-url'

返回

• event 事件
• url string

当鼠标移动到链接上或键盘将焦点移动到链接上时触发。

事件: 'cursor-changed'

返回

• event 事件
• type 字符串
• image 原生图像 （可选）
• scale 浮点数（可选） - 自定义光标的缩放比例。
• size 大小 （可选） - image 的大小。
• hotspot 点 （可选） - 自定义光标热点的坐标。

当光标类型发生变化时触发。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 事件
• params 对象
  • x 整数 - x 坐标。
  • y 整数 - y 坐标。
  • frame WebFrameMain - 从中调用上下文菜单的帧。
  • 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 矩形 - 表示选择在文档空间中的坐标的矩形。
  • selectionStartOffset 数字 - 选择文本的起始位置。
  • referrerPolicy 引荐来源 - 调用菜单的帧的引荐来源策略。
  • 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 事件
• devices BluetoothDevice[]
• callback 函数
  • deviceId 字符串

当调用 navigator.bluetooth.requestDevice 时需要选择蓝牙设备时触发。callback 应使用要选择的设备的 deviceId 进行调用。向 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'

返回

• event 事件
• 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.getBitmap())
})
win.loadURL('https://github.com')

事件: 'devtools-reload-page'

当 DevTools 窗口指示 WebContents 重新加载时触发。

事件: 'will-attach-webview'

返回

• event 事件
• webPreferences WebPreferences - 客戶端页面将使用的 Web 首选项。可以修改此对象以调整客户端页面的首选项。
• params Record<string, string> - 其他 <webview> 参数，如 src URL。可以修改此对象以调整客户端页面的参数。

当 <webview> 的 Web 内容附加到此 Web 内容时触发。调用 event.preventDefault() 将销毁客户端页面。

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

事件: 'did-attach-webview'

返回

• event 事件
• webContents WebContents - <webview> 使用的客户端 Web 内容。

当 <webview> 附加到此 Web 内容时触发。

事件: 'console-message'

返回

• event 事件
• level 整数 - 日志级别，从 0 到 3。按顺序与 verbose、info、warning 和 error 相匹配。
• message 字符串 - 实际的控制台消息
• line 整数 - 触发此控制台消息的源代码行号
• sourceId 字符串

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

事件: 'preload-error'

返回

• event 事件
• preloadPath 字符串
• error 错误

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

事件: 'ipc-message'

返回

• event IpcMainEvent
• channel 字符串
• ...args any[]

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

另见 webContents.ipc，它为专门针对此 WebContents 的 IPC 消息提供了类似 IpcMain 的接口。

事件: 'ipc-message-sync'

返回

• event IpcMainEvent
• channel 字符串
• ...args any[]

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

另见 webContents.ipc，它为专门针对此 WebContents 的 IPC 消息提供了类似 IpcMain 的接口。

事件: 'preferred-size-changed'

返回

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

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

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

事件: 'frame-created'

返回

• event 事件
• details 对象
  • frame WebFrameMain

当 mainFrame、<iframe> 或嵌套的 <iframe> 在页面中加载时触发。

实例方法

contents.loadURL(url[, options])

• url string
• options 对象 (可选)
  • httpReferrer (字符串 | Referrer) (可选) - HTTP 引用 URL。
  • userAgent 字符串 (可选) - 发出请求的用户代理。
  • extraHeaders 字符串 (可选) - 由 "\n" 分隔的额外头信息。
  • postData (UploadRawData | UploadFile)[] (可选)
  • baseURLForDataURL 字符串 (可选) - 用于通过数据 URL 加载文件的基 URL（带尾部路径分隔符）。仅当指定的 url 是数据 URL 并且需要加载其他文件时才需要此项。

返回 Promise<void> - 当页面完成加载时，该 Promise 将解析 (参见 did-finish-load)，如果页面加载失败，则拒绝 (参见 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 字符串
• options 对象 (可选)
  • query Record<string, string> (可选) - 传递给 url.format()。
  • search 字符串 (可选) - 传递给 url.format()。
  • hash 字符串 (可选) - 传递给 url.format()。

返回 Promise<void> - 当页面完成加载时，该 Promise 将解析 (参见 did-finish-load)，如果页面加载失败，则拒绝 (参见 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 对象 (可选)
  • 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 对象 (可选)
  • waitForBeforeUnload 布尔值 - 如果为 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() 已弃用

历史记录

版本	更改
>=32.0.0	API DEPRECATED

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

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

contents.canGoForward() 已弃用

历史记录

版本	更改
>=32.0.0	API DEPRECATED

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

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

contents.canGoToOffset(offset) 已弃用

历史记录

版本	更改
>=32.0.0	API DEPRECATED

• offset 整数

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

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

contents.clearHistory() 已弃用

历史记录

版本	更改
>=32.0.0	API DEPRECATED

清除导航历史记录。

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

contents.goBack() 已弃用

历史记录

版本	更改
>=32.0.0	API DEPRECATED

使浏览器后退一个网页。

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

contents.goForward() 已弃用

历史记录

版本	更改
>=32.0.0	API DEPRECATED

使浏览器前进一个网页。

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

contents.goToIndex(index) 已弃用

历史记录

版本	更改
>=32.0.0	API DEPRECATED

• index 整数

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

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

contents.goToOffset(offset) 已弃用

历史记录

版本	更改
>=32.0.0	API DEPRECATED

• offset 整数

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

已弃用： 应使用新的 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 字符串

覆盖此网页的用户代理。

contents.getUserAgent()

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

contents.insertCSS(css[, options])

• css 字符串
• options 对象 (可选)
  • cssOrigin 字符串（可选） - 可以是 'user' 或 'author'。设置插入样式表的 级联来源。默认为 'author'。

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

将 CSS 注入当前网页，并返回插入样式表的唯一键。

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

contents.removeInsertedCSS(key)

• key 字符串

返回 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 字符串
• userGesture 布尔值（可选） - 默认为 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 布尔值（可选） - 默认为 false。

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

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

contents.setIgnoreMenuShortcuts(ignore)

• ignore 布尔值

当此 web 内容处于焦点时，忽略应用程序菜单快捷键。

contents.setWindowOpenHandler(handler)

• handler Function<WindowOpenHandlerResponse>

  • details 对象
    • 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 (可选) - 将发送到新窗口的帖子数据，以及将设置的相应标头。如果没有要发送的帖子数据，该值将为 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 布尔值

静音当前网页上的音频。

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 数字 - 缩放级别。

将缩放级别更改为指定的级别。原始大小为 0，每个向上或向下的增量分别表示缩放原始大小的 20% 大或小，分别达到默认限制的 300% 和 50%。此公式为 scale := 1.2 ^ level。

注意：Chromium 级别上的缩放策略是同源策略，这意味着特定域的缩放级别会传播到具有相同域的所有窗口实例。区分窗口 URL 将使缩放按窗口进行。

contents.getZoomLevel()

返回 number - 当前缩放级别。

contents.setVisualZoomLevelLimits(minimumLevel, maximumLevel)

• minimumLevel 数字
• maximumLevel 数字

返回 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 整数
• y 整数

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

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 对象
  • 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 字符串

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

contents.replaceMisspelling(text)

• text 字符串

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

contents.insertText(text)

• text 字符串

返回 Promise<void>

在聚焦元素中插入text。

contents.findInPage(text[, options])

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

返回整数 - 请求的请求 ID。

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

contents.stopFindInPage(action)

• action 字符串 - 指定在结束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 矩形（可选） - 要捕获的页面区域。
• opts 对象 (可选)
  • stayHidden 布尔值（可选） - 保持页面隐藏而不是可见。默认值为false。
  • stayAwake 布尔值（可选） - 保持系统唤醒状态，而不是允许其进入睡眠状态。默认值为false。

返回Promise<NativeImage> - 使用NativeImage解析。

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

contents.isBeingCaptured()

返回布尔值 - 此页面是否正在捕获。当捕获器计数大于 0 时，它将返回 true。

contents.getPrintersAsync()

获取系统打印机列表。

返回Promise<PrinterInfo[]> - 使用PrinterInfo[]解析。

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

• options 对象 (可选)
  • 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 字符串 | 大小（可选） - 指定打印文档的页面大小。可以是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 将选择系统的默认打印机，并使用默认的打印设置。

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

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

将窗口的网页打印为 PDF。

如果网页中使用 @page CSS 规则，landscape 将被忽略。

webContents.printToPDF 的示例

const { app, BrowserWindow } = require('electron')
const fs = require('node:fs')
const path = require('node:path')
const os = require('node:os')

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 字符串

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

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

contents.removeWorkSpace(path)

• path 字符串

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

contents.setDevToolsWebContents(devToolsWebContents)

• devToolsWebContents WebContents

使用 devToolsWebContents 作为目标 WebContents 来显示开发者工具。

devToolsWebContents 不得进行任何导航，并且在调用后不应用于其他目的。

默认情况下，Electron 通过创建具有本机视图的内部 WebContents 来管理开发者工具，开发者对其控制非常有限。使用 setDevToolsWebContents 方法，开发者可以使用任何 WebContents 在其中显示开发者工具，包括 BrowserWindow、BrowserView 和 <webview> 标签。

请注意，关闭开发者工具不会销毁 devToolsWebContents，销毁 devToolsWebContents 是调用者的责任。

在 <webview> 标签中显示开发者工具的示例

<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 中显示开发者工具的示例

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 对象 (可选)
  • mode 字符串 - 以指定的停靠状态打开开发者工具，可以是 left、right、bottom、undocked、detach。默认为上次使用的停靠状态。在 undocked 模式下，可以停靠回来。在 detach 模式下，则不能。
  • activate 布尔值（可选） - 是否将打开的开发者工具窗口置于前台。默认为 true。
  • title 字符串（可选） - 开发者工具窗口的标题（仅在 undocked 或 detach 模式下）。

打开开发者工具。

当 contents 是 <webview> 标签时，mode 默认情况下将为 detach，明确传递一个空 mode 可以强制使用上次使用的停靠状态。

在 Windows 上，如果启用了 Windows 控制叠加层，开发者工具将以 mode: 'detach' 模式打开。

contents.closeDevTools()

关闭开发者工具。

contents.isDevToolsOpened()

返回 boolean - 开发者工具是否打开。

contents.isDevToolsFocused()

返回 boolean - 开发者工具视图是否处于焦点。

contents.getDevToolsTitle()

返回 string - 开发者工具窗口的当前标题。这只有在以 undocked 或 detach 模式打开开发者工具时才可见。

contents.setDevToolsTitle(title)

• title 字符串

将开发者工具窗口的标题更改为 title。这只有在以 undocked 或 detach 模式打开开发者工具时才可见。

contents.toggleDevTools()

切换开发者工具。

contents.inspectElement(x, y)

• x 整数
• y 整数

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

contents.inspectSharedWorker()

为共享工作程序上下文打开开发者工具。

contents.inspectSharedWorkerById(workerId)

• workerId 字符串

根据其 ID 检查共享工作程序。

contents.getAllSharedWorkers()

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

contents.inspectServiceWorker()

为服务工作程序上下文打开开发者工具。

contents.send(channel, ...args)

• channel 字符串
• ...args any[]

通过 channel 向渲染器进程发送异步消息，以及参数。参数将使用 结构化克隆算法 进行序列化，就像 postMessage 一样，因此不会包含原型链。发送函数、Promise、符号、弱映射或弱集将引发异常。

警告

发送非标准 JavaScript 类型（如 DOM 对象或特殊的 Electron 对象）将引发异常。

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

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

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

通过 channel 向渲染器进程中的特定框架发送异步消息，以及参数。参数将使用 结构化克隆算法 进行序列化，就像 postMessage 一样，因此不会包含原型链。发送函数、Promise、符号、弱映射或弱集将引发异常。

注意： 发送非标准 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 字符串
• message 任何
• 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 大小 - 设置模拟屏幕尺寸 (screenPosition == mobile)。
  • viewPosition 点 - 在屏幕上定位视图 (screenPosition == mobile)（默认：{ x: 0, y: 0 }）。
  • deviceScaleFactor 整数 - 设置设备比例因子（如果为零，则默认为原始设备比例因子）（默认：0）。
  • viewSize 大小 - 设置模拟视图尺寸（空表示不覆盖）
  • scale 浮点数 - 模拟视图在可用空间内的比例（不在适合视图模式下）（默认：1）。

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

contents.disableDeviceEmulation()

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

contents.sendInputEvent(inputEvent)

• inputEvent 鼠标输入事件 | 鼠标滚轮输入事件 | 键盘输入事件

向页面发送输入 event。注意： 包含内容的 BrowserWindow 需要处于焦点状态，sendInputEvent() 才能正常工作。

contents.beginFrameSubscription([onlyDirty ,]callback)

• onlyDirty 布尔值（可选） - 默认为 false。
• callback 函数
  • image 原生图像
  • dirtyRect Rectangle

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

image 是一个存储捕获帧的 原生图像 实例。

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

contents.endFrameSubscription()

结束订阅帧演示事件。

contents.startDrag(item)

• item 对象
  • file 字符串 - 被拖动的文件的路径。
  • files 字符串数组（可选） - 被拖动的文件的路径。（files 会覆盖 file 字段）
  • icon 原生图片 | 字符串 - 在 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()

安排对包含此 web 内容的窗口进行全面重绘。

如果启用了离屏渲染，则使帧无效并通过'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。使用此策略时，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)

历史记录

版本	更改
>=28.0.0	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 上注册的处理程序或事件监听器将接收从任何帧发送的 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属性，用于将网页内容的帧速率设置为指定数字。仅接受 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

历史记录

版本	更改
>=28.0.0	WebContents.backgroundThrottling 设置为 false 会影响主机 BrowserWindow 中的所有 WebContents

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

contents.mainFrame 只读

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

contents.opener 只读

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