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

框架导航

The will-navigate and did-navigate events only fire when the mainFrame navigates. If you want to also observe navigations in <iframe>s, use will-frame-navigate and did-frame-navigate events.

方法

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

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

webContents.getAllWebContents()

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

webContents.getFocusedWebContents()

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

webContents.fromId(id)

• id Integer

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

webContents.fromFrame(frame)

• frame WebFrameMain

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

webContents.fromDevToolsTargetId(targetId)

• targetId string - 与 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 Event
• errorCode Integer
• errorDescription string
• validatedURL string
• isMainFrame boolean
• frameProcessId Integer
• frameRoutingId Integer

此事件与 did-finish-load 类似，但在加载失败时触发。 错误码及其含义的完整列表可从 此处 获取。

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

返回值

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

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

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

返回值

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

帧完成导航时触发。

事件：'did-start-loading'

对应于标签页加载指示器开始旋转的时间点。

事件：'did-stop-loading'

对应于标签页加载指示器停止旋转的时间点。

事件：'dom-ready'

顶级帧中的文档加载完成后触发。

事件：'page-title-updated'

返回值

• event Event
• title string
• explicitSet boolean

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

事件：'page-favicon-updated'

返回值

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

页面接收到 favicon url 时触发。

事件：'content-bounds-updated'

返回值

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

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

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

事件：'did-create-window'

返回值

• window BrowserWindow
• details Object
  • url string - 创建窗口的 URL。
  • frameName string - 在 window.open() 调用中赋予创建窗口的名称。
  • options BrowserWindowConstructorOptions - 用于创建 BrowserWindow 的选项。 它们按优先级递增顺序合并：从 window.open() 的 features 字符串解析的选项、从父级继承的安全相关 webPreferences，以及通过 webContents.setWindowOpenHandler 给定的选项。 未识别的选项不会被过滤掉。
  • referrer Referrer - 将传递给新窗口的 referrer。 根据 referrer 策略，可能发送或不发送 Referer 头。
  • postBody PostBody (可选) - 将与适当的头部一起发送到新窗口的 POST 数据。 如果没有 POST 数据要发送，则值为 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 | 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 Event<>
  • 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 对象更改或用户单击页面中的链接时，可能会发生这种情况。

Unlike will-navigate, will-frame-navigate is fired when the main frame or any of its subframes attempts to navigate. When the navigation event comes from the main frame, isMainFrame will be 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 | null - 要导航的框架。 如果在框架导航或销毁后访问，可能为 null。
  • initiator WebFrameMain | null (可选) - 发起导航的框架，可以是父框架 (例如，通过带有框架名称的 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 | 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 Event<>
  • 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'

无响应的网页再次响应时触发。

事件：'plugin-crashed'

返回值

• event Event
• name string
• version string

插件进程崩溃时触发。

事件：'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 { 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 Event
• zoomDirection string - 可以是 in (放大) 或 out (缩小)。

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

事件：'blur'

WebContents 失去焦点时触发。

事件：'focus'

WebContents 获得焦点时触发。

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

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 - 调用菜单时所处的帧的 referrer policy。
  • 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 string

当调用 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'

返回值

• details Event<>
  • 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)，您可以在 Chromium 硬件加速的支持下，将纹理句柄传递给外部渲染管线，而无需在 CPU 和 GPU 内存之间复制数据。 此功能有助于实现高性能渲染场景。

同时存在的纹理数量有限，因此在您使用完纹理后立即调用 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'

当开发者工具窗口指示 webContents 重新加载时触发。

事件：'will-attach-webview'

返回值

• event Event
• webPreferences WebPreferences - 访客页面将使用的 WebPreferences。 可以修改此对象以调整访客页面的偏好设置。
• params Record<string, string> - 其他 <webview> 参数，例如 src URL。 可以修改此对象以调整访客页面的参数。

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

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

事件：'did-attach-webview'

返回值

• event Event
• webContents WebContents - <webview> 所使用的访客 web 内容。

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

事件：'console-message'

返回值

• details Event<>
  • 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 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" 分隔的额外 HTTP 头。
  • postData (UploadRawData | UploadFile)[] (可选)
  • baseURLForDataURL string (可选) - data url 加载文件时使用的基 URL (带有尾随路径分隔符)。 仅当指定的 url 是 data 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 string
• options Object (可选)
  • query Record<string, string> (可选) - 传递给 url.format()。
  • search string (可选) - 传递给 url.format()。
  • hash string (可选) - 传递给 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 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 事件。

关闭页面，就像网页内容调用了 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() 已废弃

历史记录

版本	更改
None	API DEPRECATED

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

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

contents.canGoForward() 已废弃

历史记录

版本	更改
None	API DEPRECATED

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

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

contents.canGoToOffset(offset) 已废弃

历史记录

版本	更改
None	API DEPRECATED

• offset Integer

返回 boolean - 网页是否可以跳转到 offset 指定的条目。

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

contents.clearHistory() 已废弃

历史记录

版本	更改
None	API DEPRECATED

清空导航历史记录。

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

contents.goBack() 已废弃

历史记录

版本	更改
None	API DEPRECATED

使浏览器回退一页。

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

contents.goForward() 已废弃

历史记录

版本	更改
None	API DEPRECATED

使浏览器前进一页。

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

contents.goToIndex(index) 已废弃

历史记录

版本	更改
None	API DEPRECATED

• index Integer

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

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

contents.goToOffset(offset) 已废弃

历史记录

版本	更改
None	API DEPRECATED

• offset Integer

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

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

contents.isCrashed()

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

contents.forcefullyCrashRenderer()

强制终止当前托管此 webContents 的渲染器进程。 这将导致触发 render-process-gone 事件，其 reason 为 killed || 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 并返回插入样式表的唯一键。

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，则此 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，则此 Promise 会被拒绝。

工作方式与 executeJavaScript 类似，但在隔离的上下文环境中执行 scripts。

contents.setIgnoreMenuShortcuts(ignore)

• ignore boolean

当此 web 内容获得焦点时，忽略应用程序菜单快捷方式。

contents.setWindowOpenHandler(handler)

• handler Function<WindowOpenHandlerResponse>

  • details Object
    • url string - 传递给 window.open() 的 URL 的解析后版本。 例如，使用 window.open('foo') 打开窗口将产生类似于 https://the-origin/the/current/path/foo 的 URL。
    • frameName string - window.open() 中提供的窗口名称。
    • features string - 传递给 window.open() 的窗口特性列表，逗号分隔。
    • disposition string - 可以是 default (默认), foreground-tab (前台标签页), background-tab (后台标签页), new-window (新窗口) 或 other (其他)。
    • referrer Referrer - 将传递给新窗口的 referrer。 根据 referrer 策略，可能发送或不发送 Referer 头。
    • postBody PostBody (可选) - 将与适当的头部一起发送到新窗口的 POST 数据。 如果没有 POST 数据要发送，则值为 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> - Promise 成功时带上 NativeImage

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

contents.isBeingCaptured()

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

contents.getPrintersAsync()

获取系统打印机列表。

返回 Promise<PrinterInfo[]> - Promise 成功时带上 PrinterInfo[]

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

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

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

返回 Promise<Buffer> - Promise 成功时带上生成的 PDF 数据。

将窗口的网页打印为 PDF。

如果在网页中使用了 @page CSS at-rule，则 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 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 作为目标 WebContents 来显示 devtools。

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 string - 以指定的停靠状态打开 devtools，可以是 left、right、bottom、undocked、detach。默认为上次使用的停靠状态。在 undocked 模式下可以重新停靠。在 detach 模式下不能。
  • activate boolean (可选) - 是否将打开的 devtools 窗口带到前台。默认值为 true。
  • title string (可选) - DevTools 窗口的标题 (仅在 undocked 或 detach 模式下有效)。

打开 devtools。

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

在 Windows 上，如果启用了 Windows 控制覆盖，Devtools 将以 mode: 'detach' 模式打开。

contents.closeDevTools()

关闭 devtools。

contents.isDevToolsOpened()

返回 boolean - devtools 是否已打开。

contents.isDevToolsFocused()

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

contents.getDevToolsTitle()

返回 string - DevTools 窗口的当前标题。这仅在 DevTools 以 undocked 或 detach 模式打开时可见。

contents.setDevToolsTitle(title)

• title string

将 DevTools 窗口的标题更改为 title。这仅在 DevTools 以 undocked 或 detach 模式打开时可见。

contents.toggleDevTools()

切换开发者工具。

contents.inspectElement(x, y)

• x Integer
• y Integer

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

contents.inspectSharedWorker()

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

contents.inspectSharedWorkerById(workerId)

• workerId string

根据 ID 检查共享 worker。

contents.getAllSharedWorkers()

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

contents.inspectServiceWorker()

为 Service Worker 上下文打开开发者工具。

contents.send(channel, ...args)

• channel string
• ...args any[]

通过 channel 向渲染进程发送异步消息，以及参数。参数将使用 Structured Clone Algorithm 进行序列化，就像 postMessage 一样，因此不会包含原型链。发送函数、Promise、Symbol、WeakMap 或 WeakSet 将抛出异常。

warning

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

更多阅读请参考 Electron 的 IPC 指南。

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

• frameId Integer | [number, number] - 要发送消息的 frame ID，如果 frame 与主 frame 在不同进程中，则为一个 [processId, frameId] 对。
• channel string
• ...args any[]

通过 channel 向渲染进程中的特定 frame 发送异步消息，以及参数。参数将使用 Structured Clone Algorithm 进行序列化，就像 postMessage 一样，因此不会包含原型链。发送函数、Promise、Symbol、WeakMap 或 WeakSet 将抛出异常。

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

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

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

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

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

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

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

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

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

转移的 MessagePortMain 对象将通过访问触发的事件的 ports 属性在渲染进程中可用。当它们到达渲染器时，它们将是原生的 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 Object
  • screenPosition string - 指定模拟的屏幕类型 (默认: desktop)
    • desktop - 桌面屏幕类型。
    • mobile - 移动屏幕类型。
  • screenSize Size - 设置模拟屏幕尺寸 (screenPosition == mobile)。
  • viewPosition Point - 设置视图在屏幕上的位置 (screenPosition == mobile) (默认: { x: 0, y: 0 })。
  • deviceScaleFactor Integer - 设置设备缩放比例 (如果为零则默认为原始设备缩放比例) (默认: 0)。
  • viewSize Size - 设置模拟视图尺寸 (为空表示不覆盖)。
  • scale Float - 可用空间内模拟视图的缩放比例 (非适应视图模式下) (默认: 1)。

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

contents.disableDeviceEmulation()

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

contents.sendInputEvent(inputEvent)

• inputEvent MouseInputEvent | MouseWheelInputEvent | KeyboardInputEvent

向页面发送输入 event。注意：包含此内容的 BrowserWindow 需要获得焦点才能使 sendInputEvent() 工作。

contents.beginFrameSubscription([onlyDirty ,]callback)

• onlyDirty boolean (可选) - 默认为 false。
• callback Function
  • image NativeImage
  • dirtyRect Rectangle

开始订阅呈现事件和捕获的 frame，当有呈现事件发生时，callback 将会被调用，格式为 callback(image, dirtyRect)。

image 是存储捕获到的 frame 的 NativeImage 实例。

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

contents.endFrameSubscription()

结束订阅 frame 呈现事件。

contents.startDrag(item)

• item Object
  • file string - 要拖动的文件路径。
  • files string[] (可选) - 要拖动的文件路径数组。(files 将覆盖 file 字段)
  • icon NativeImage | string - 在 macOS 上，图像必须非空。

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

contents.savePage(fullPath, saveType)

• fullPath string - 绝对文件路径。
• saveType string - 指定保存类型。
  • 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 Integer

如果启用了 离屏渲染，则将帧率设置为指定数值。只接受介于 1 和 240 之间的值。

contents.getFrameRate()

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

contents.invalidate()

安排对此 web contents 所在窗口进行一次完整重绘。

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

contents.getWebRTCIPHandlingPolicy()

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

contents.setWebRTCIPHandlingPolicy(policy)

• policy string - 指定 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 Integer - WebRTC 应使用的最小 UDP 端口号。
• max Integer - WebRTC 应使用的最大 UDP 端口号。

默认情况下，此值为 { min: 0, max: 0 }，表示对 UDP 端口范围不施加限制。

contents.setWebRTCUDPPortRange(udpPortRange)

• udpPortRange Object
  • min Integer - WebRTC 应使用的最小 UDP 端口号。
  • max Integer - WebRTC 应使用的最大 UDP 端口号。

设置 WebRTC UDP 端口范围允许您限制 WebRTC 使用的 UDP 端口范围。默认情况下，端口范围不受限制。注意：要重置为不受限制的端口范围，此值应设置为 { min: 0, max: 0 }。

contents.getMediaSourceId(requestWebContents)

• requestWebContents WebContents - ID 将注册到的 Web contents。

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

contents.getOSProcessId()

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

contents.getProcessId()

返回 Integer - 相关渲染器的 Chromium 内部 pid。可以与 frame 特定导航事件 (例如 did-frame-navigate) 传递的 frameProcessId 进行比较。

contents.takeHeapSnapshot(filePath)

• filePath string - 输出文件路径。

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

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

contents.getBackgroundThrottling()

返回 boolean - 此 WebContents 在页面进入后台时是否会限制动画和计时器。这也会影响 Page Visibility API。

contents.setBackgroundThrottling(allowed)

历史记录

版本	更改
None	将 WebContents.backgroundThrottling 设置为 false 会影响宿主 BrowserWindow 中的所有 WebContents。

• allowed boolean

控制此 WebContents 在页面进入后台时是否限制动画和计时器。这也会影响 Page Visibility API。

contents.getType()

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

contents.setImageAnimationPolicy(policy)

• policy string - 可以是 animate、animateOnce 或 noAnimation。

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

这对应于 Chromium 中的 animationPolicy 辅助功能。

实例属性

contents.ipc 只读

一个仅作用于从此 WebContents 发送的 IPC 消息的 IpcMain 实例。

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

历史记录

版本	更改
None	将 WebContents.backgroundThrottling 设置为 false 会影响宿主 BrowserWindow 中的所有 WebContents。

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

contents.mainFrame 只读

一个 WebFrameMain 属性，表示页面 frame 层级的顶部 frame。

contents.opener 只读

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

contents.focusedFrame 只读

一个 WebFrameMain | null 属性，表示此 WebContents 中当前获得焦点的 frame。 可以是顶部 frame、内部