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()
,则后续事件将不会触发。
页面内导航
页面内导航不会导致页面重新加载,而是导航到当前页面中的某个位置。这些事件不可取消。对于页面内导航,将按此顺序触发以下事件
框架导航
will-navigate
和 did-navigate
事件仅在 mainFrame 导航时触发。如果您还想观察 <iframe>
中的导航,请使用 will-frame-navigate
和 did-frame-navigate
事件。
方法
这些方法可以从 webContents
模块访问
const { webContents } = require('electron')
console.log(webContents)
webContents.getAllWebContents()
返回 WebContents[]
- 所有 WebContents
实例的数组。这将包含所有窗口、 webview、 打开的开发工具和开发工具扩展背景页面的 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
string - 与 WebContents 实例关联的 Chrome DevTools Protocol TargetID。
返回 WebContents | undefined
- 具有给定 TargetID 的 WebContents 实例,如果不存在与给定 TargetID 关联的 WebContents,则返回 undefined
。
在与 Chrome DevTools Protocol 通信时,根据其分配的 TargetID 查找 WebContents 实例非常有用。
async function lookupTargetId (browserWindow) {
const wc = browserWindow.webContents
await wc.debugger.attach('1.3')
const { targetInfo } = await wc.debugger.sendCommand('Target.getTargetInfo')
const { targetId } = targetInfo
const targetWebContents = await wc.fromDevToolsTargetId(targetId)
}
类: WebContents
渲染和控制 BrowserWindow 实例的内容。
进程: 主进程
此类不从 'electron'
模块导出。它仅作为 Electron API 中其他方法的返回值提供。
实例事件
事件: 'did-finish-load'
当导航完成时发出,即选项卡的微调器已停止旋转,并且已分派 onload
事件。
事件: 'did-fail-load'
返回
event
事件errorCode
整数errorDescription
字符串validatedURL
字符串isMainFrame
布尔值frameProcessId
整数frameRoutingId
整数
此事件类似于 did-finish-load
,但在加载失败时发出。错误代码及其含义的完整列表可在此处找到 here。
事件: '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
string[] - URL 数组。
当页面收到网站图标 URL 时发出。
事件: 'content-bounds-updated'
返回
event
事件bounds
矩形 - 请求的新内容边界
当页面调用 window.moveTo
、window.resizeTo
或相关 API 时发出。
默认情况下,这将移动窗口。要阻止该行为,请调用 event.preventDefault()
。
事件: 'did-create-window'
返回
window
BrowserWindowdetails
对象url
字符串 - 创建窗口的 URL。frameName
字符串 - 在window.open()
调用中赋予已创建窗口的名称。referrer
引用器 - 将传递到新窗口的引用器。 可能不会导致发送Referer
标头,具体取决于引用器策略。postBody
PostBody(可选) - 将发送到新窗口的 post 数据,以及将设置的相应标头。 如果没有要发送的 post 数据,则该值将为null
。 仅在窗口由设置了target=_blank
的表单创建时定义。disposition
字符串 - 可以是default
、foreground-tab
、background-tab
、new-window
或other
。
在渲染器中通过 window.open
成功创建窗口后发出。 如果窗口的创建从 webContents.setWindowOpenHandler
中取消,则不会发出。
有关更多详细信息以及如何在与 webContents.setWindowOpenHandler
结合使用,请参阅 window.open()
。
事件: 'will-navigate'
返回
details
事件<>url
字符串 - 框架要导航到的 URL。isSameDocument
布尔值 - 此事件不会为使用 window.history api 和引用片段导航的相同文档导航触发。 此属性始终为此事件设置为false
。isMainFrame
布尔值 - 如果导航发生在主框架中,则为 True。frame
WebFrameMain | null - 要导航的框架。 如果在框架已导航或被销毁后访问,则可能为null
。initiator
WebFrameMain | null (可选) - 启动导航的框架,它可以是父框架(例如,通过具有框架名称的window.open
),或者如果导航不是由框架启动,则为 null。 如果启动框架在发出事件之前被删除,则这也可能为 null。
url
字符串 已弃用isInPlace
布尔值 已弃用isMainFrame
布尔值 已弃用frameProcessId
整数 已弃用frameRoutingId
整数 已弃用
当用户或页面想要在主框架上启动导航时发出。 当 window.location
对象更改或用户单击页面中的链接时,可能会发生这种情况。
当使用诸如 webContents.loadURL
和 webContents.back
等 API 以编程方式启动导航时,不会发出此事件。
它也不会为页面内导航发出,例如单击锚点链接或更新 window.location.hash
。 使用 did-navigate-in-page
事件来实现此目的。
调用 event.preventDefault()
将阻止导航。
事件: 'will-frame-navigate'
返回
details
事件<>url
字符串 - 框架要导航到的 URL。isSameDocument
布尔值 - 此事件不会为使用 window.history api 和引用片段导航的相同文档导航触发。 此属性始终为此事件设置为false
。isMainFrame
布尔值 - 如果导航发生在主框架中,则为 True。frame
WebFrameMain | null - 要导航的框架。 如果在框架已导航或被销毁后访问,则可能为null
。initiator
WebFrameMain | null (可选) - 启动导航的框架,它可以是父框架(例如,通过具有框架名称的window.open
),或者如果导航不是由框架启动,则为 null。 如果启动框架在发出事件之前被删除,则这也可能为 null。
当用户或页面想要在任何框架中启动导航时发出。 当 window.location
对象更改或用户单击页面中的链接时,可能会发生这种情况。
与 will-navigate
不同,当主框架或其任何子框架尝试导航时,将触发 will-frame-navigate
。 当导航事件来自主框架时,isMainFrame
将为 true
。
当使用诸如 webContents.loadURL
和 webContents.back
等 API 以编程方式启动导航时,不会发出此事件。
它也不会为页面内导航发出,例如单击锚点链接或更新 window.location.hash
。 使用 did-navigate-in-page
事件来实现此目的。
调用 event.preventDefault()
将阻止导航。
事件: 'did-start-navigation'
返回
details
事件<>url
字符串 - 框架要导航到的 URL。isSameDocument
布尔值 - 导航是否发生在不更改文档的情况下。 相同文档导航的示例包括引用片段导航、pushState/replaceState 和相同页面历史记录导航。isMainFrame
布尔值 - 如果导航发生在主框架中,则为 True。frame
WebFrameMain | null - 要导航的框架。 如果在框架已导航或被销毁后访问,则可能为null
。initiator
WebFrameMain | null (可选) - 启动导航的框架,它可以是父框架(例如,通过具有框架名称的window.open
),或者如果导航不是由框架启动,则为 null。 如果启动框架在发出事件之前被删除,则这也可能为 null。
url
字符串 已弃用isInPlace
布尔值 已弃用isMainFrame
布尔值 已弃用frameProcessId
整数 已弃用frameRoutingId
整数 已弃用
当任何框架(包括主框架)开始导航时发出。
事件: 'will-redirect'
返回
details
事件<>url
字符串 - 框架要导航到的 URL。isSameDocument
布尔值 - 导航是否发生在不更改文档的情况下。 相同文档导航的示例包括引用片段导航、pushState/replaceState 和相同页面历史记录导航。isMainFrame
布尔值 - 如果导航发生在主框架中,则为 True。frame
WebFrameMain | null - 要导航的框架。 如果在框架已导航或被销毁后访问,则可能为null
。initiator
WebFrameMain | null (可选) - 启动导航的框架,它可以是父框架(例如,通过具有框架名称的window.open
),或者如果导航不是由框架启动,则为 null。 如果启动框架在发出事件之前被删除,则这也可能为 null。
url
字符串 已弃用isInPlace
布尔值 已弃用isMainFrame
布尔值 已弃用frameProcessId
整数 已弃用frameRoutingId
整数 已弃用
当服务器端重定向在导航期间发生时发出。 例如 302 重定向。
此事件将在 did-start-navigation
之后发出,并且始终在同一导航的 did-redirect-navigation
事件之前发出。
调用 event.preventDefault()
将阻止导航(而不仅仅是重定向)。
事件: 'did-redirect-navigation'
返回
details
事件<>url
字符串 - 框架要导航到的 URL。isSameDocument
布尔值 - 导航是否发生在不更改文档的情况下。 相同文档导航的示例包括引用片段导航、pushState/replaceState 和相同页面历史记录导航。isMainFrame
布尔值 - 如果导航发生在主框架中,则为 True。frame
WebFrameMain | null - 要导航的框架。 如果在框架已导航或被销毁后访问,则可能为null
。initiator
WebFrameMain | null (可选) - 启动导航的框架,它可以是父框架(例如,通过具有框架名称的window.open
),或者如果导航不是由框架启动,则为 null。 如果启动框架在发出事件之前被删除,则这也可能为 null。
url
字符串 已弃用isInPlace
布尔值 已弃用isMainFrame
布尔值 已弃用frameProcessId
整数 已弃用frameRoutingId
整数 已弃用
当服务器端重定向在导航期间发生后发出。 例如 302 重定向。
此事件无法阻止,如果要阻止重定向,则应检查上面的 will-redirect
事件。
事件: 'did-navigate'
返回
event
事件url
字符串httpResponseCode
整数 - -1 用于非 HTTP 导航httpStatusText
字符串 - 对于非 HTTP 导航为空
当主框架导航完成时发出。
此事件不会为页面内导航发出,例如单击锚点链接或更新 window.location.hash
。 使用 did-navigate-in-page
事件来实现此目的。
事件: 'did-frame-navigate'
返回
event
事件url
字符串httpResponseCode
整数 - -1 用于非 HTTP 导航httpStatusText
字符串 - 对于非 HTTP 导航为空,isMainFrame
布尔值frameProcessId
整数frameRoutingId
整数
当任何框架导航完成时发出。
此事件不会为页面内导航发出,例如单击锚点链接或更新 window.location.hash
。 使用 did-navigate-in-page
事件来实现此目的。
事件: 'did-navigate-in-page'
返回
event
事件url
字符串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,如果每个 specification 都存在。
事件: 'render-process-gone'
返回
event
事件details
RenderProcessGoneDetails
当渲染器进程意外消失时发出。 这通常是因为它已崩溃或被终止。
事件: 'unresponsive'
当网页变得无响应时发出。
事件: 'responsive'
当无响应的网页再次变为响应时发出。
事件: 'plugin-crashed'
返回
event
事件name
字符串version
字符串
当插件进程崩溃时发出。
事件: 'destroyed'
当 webContents
被销毁时触发。
事件: 'input-event'
返回
event
事件inputEvent
InputEvent
当输入事件发送到 WebContents 时触发。 详情请参阅 InputEvent。
事件: 'before-input-event'
返回
event
事件input
对象 - 输入属性。type
字符串 -keyUp
或keyDown
。key
字符串 - 相当于 KeyboardEvent.key。code
字符串 - 相当于 KeyboardEvent.code。isAutoRepeat
布尔值 - 相当于 KeyboardEvent.repeat。isComposing
布尔值 - 相当于 KeyboardEvent.isComposing。shift
布尔值 - 相当于 KeyboardEvent.shiftKey。control
布尔值 - 相当于 KeyboardEvent.controlKey。alt
布尔值 - 相当于 KeyboardEvent.altKey。meta
布尔值 - 相当于 KeyboardEvent.metaKey。location
数字 - 相当于 KeyboardEvent.location。modifiers
字符串[] - 参见 InputEvent.modifiers。
在页面中派发 keydown
和 keyup
事件之前触发。 调用 event.preventDefault
将阻止页面 keydown
/keyup
事件和菜单快捷方式。
要仅阻止菜单快捷方式,请使用 setIgnoreMenuShortcuts
const { app, BrowserWindow } = require('electron')
app.whenReady().then(() => {
const win = new BrowserWindow({ width: 800, height: 600 })
win.webContents.on('before-input-event', (event, input) => {
// Enable application menu keyboard shortcuts when Ctrl/Cmd are down.
win.webContents.setIgnoreMenuShortcuts(!input.control && !input.meta)
})
})
事件: 'before-mouse-event'
返回
event
事件mouse
MouseInputEvent
在页面中派发鼠标事件之前触发。
调用 event.preventDefault
将阻止页面鼠标事件。
const { app, BrowserWindow } = require('electron')
app.whenReady().then(() => {
const win = new BrowserWindow({ width: 800, height: 600 })
win.webContents.on('before-mouse-event', (event, mouse) => {
// Prevent mouseDown events.
if (mouse.type === 'mouseDown') {
console.log(mouse)
/*
{
type: 'mouseDown',
clickCount: 1,
movementX: 0,
movementY: 0,
button: 'left',
x: 632.359375,
y: 480.6875,
globalX: 168.359375,
globalY: 193.6875
}
*/
event.preventDefault()
}
})
})
事件: 'enter-html-full-screen'
当窗口进入由 HTML API 触发的全屏状态时触发。
事件: 'leave-html-full-screen'
当窗口离开由 HTML API 触发的全屏状态时触发。
事件: 'zoom-changed'
返回
event
事件zoomDirection
字符串 - 可以是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
字符串error
字符串 - 错误代码。certificate
Certificatecallback
函数isTrusted
布尔值 - 指示证书是否可以被认为是可信的。
isMainFrame
布尔值
当无法验证 url
的 certificate
时触发。
用法与 app
的 certificate-error
事件 相同。
事件: 'select-client-certificate'
返回
event
事件url
URLcertificateList
Certificate[]callback
函数certificate
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
发出音频,则为 True。
当媒体变得可听或不可听时触发。
事件: 'did-change-theme-color'
返回
event
事件color
(字符串 | null) - 主题颜色为 '#rrggbb' 格式。 当未设置主题颜色时,它为null
。
当页面的主题颜色更改时触发。 这通常是由于遇到 meta 标签
<meta name='theme-color' content='#ff0000'>
事件: 'update-target-url'
返回
event
事件url
字符串
当鼠标移动到链接上或键盘将焦点移动到链接时触发。
事件: 'cursor-changed'
返回
event
事件type
字符串image
NativeImage (可选)scale
浮点数 (可选) - 自定义光标的缩放因子。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
事件params
对象x
整数 - x 坐标。y
整数 - y 坐标。frame
WebFrameMain | null - 调用上下文菜单的框架。 如果在框架导航或销毁后访问,则可能为null
。linkURL
字符串 - 包含调用上下文菜单的节点的链接的 URL。linkText
字符串 - 与链接关联的文本。 如果链接的内容是图像,则可能为空字符串。pageURL
字符串 - 调用上下文菜单的顶层页面的 URL。frameURL
字符串 - 调用上下文菜单的子框架的 URL。srcURL
字符串 - 调用上下文菜单的元素的源 URL。 具有源 URL 的元素是图像、音频和视频。mediaType
字符串 - 调用上下文菜单的节点的类型。 可以是none
、image
、audio
、video
、canvas
、file
或plugin
。hasImageContents
布尔值 - 上下文菜单是否在具有非空内容的图像上调用。isEditable
布尔值 - 上下文是否可编辑。selectionText
字符串 - 调用上下文菜单的选中文本。titleText
字符串 - 选中文本的标题文本。altText
字符串 - 选中文本的 Alt 文本。suggestedFilename
字符串 - 通过上下文菜单的“链接另存为”选项保存文件时使用的建议文件名。selectionRect
Rectangle - 表示文档空间中选择坐标的矩形。selectionStartOffset
数字 - 选中文本的起始位置。referrerPolicy
Referrer - 调用菜单的框架的引用策略。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
时需要选择蓝牙设备时触发。 应使用要选择的设备的 deviceId
调用 callback
。 将空字符串传递给 callback
将取消请求。
如果未为此事件添加任何事件侦听器,则所有蓝牙请求都将被取消。
如果在处理此事件时未调用 event.preventDefault
,则将自动选择第一个可用设备。
由于蓝牙的性质,当调用 navigator.bluetooth.requestDevice
时扫描设备可能需要时间,并且会导致 select-bluetooth-device
多次触发,直到使用设备 ID 或空字符串调用 callback
以取消请求。
const { app, BrowserWindow } = require('electron')
let win = null
app.whenReady().then(() => {
win = new BrowserWindow({ width: 800, height: 600 })
win.webContents.on('select-bluetooth-device', (event, deviceList, callback) => {
event.preventDefault()
const result = deviceList.find((device) => {
return device.deviceName === 'test'
})
if (!result) {
// The device wasn't found so we need to either wait longer (eg until the
// device is turned on) or cancel the request by calling the callback
// with an empty string.
callback('')
} else {
callback(result.deviceId)
}
})
})
事件: 'paint'
返回
details
事件<>texture
OffscreenSharedTexture (可选) Experimental - 当webPreferences.offscreen.useSharedTexture
为true
时,帧的 GPU 共享纹理。
dirtyRect
Rectangleimage
NativeImage - 整个帧的图像数据。
当生成新帧时触发。 只有脏区域在缓冲区中传递。
const { BrowserWindow } = require('electron')
const win = new BrowserWindow({ webPreferences: { offscreen: true } })
win.webContents.on('paint', (event, dirty, image) => {
// updateBitmap(dirty, image.toBitmap())
})
win.loadURL('https://github.com')
当使用共享纹理(将 webPreferences.offscreen.useSharedTexture
设置为 true
)功能时,您可以将纹理句柄传递给外部渲染管道,而无需在 CPU 和 GPU 内存之间复制数据的开销,并具有 Chromium 的硬件加速支持。 此功能对高性能渲染场景很有用。
同时只能存在有限数量的纹理,因此尽快调用 texture.release()
非常重要。 通过自己管理纹理生命周期,您可以安全地通过 IPC 将 texture.textureInfo
传递给其他进程。
更多详细信息可以在 离屏渲染教程 中找到。 要了解如何在原生代码中处理纹理,请参阅 离屏渲染的代码文档。。
const { BrowserWindow } = require('electron')
const win = new BrowserWindow({ webPreferences: { offscreen: { useSharedTexture: true } } })
win.webContents.on('paint', async (e, dirty, image) => {
if (e.texture) {
// By managing lifecycle yourself, you can handle the event in async handler or pass the `e.texture.textureInfo`
// to other processes (not `e.texture`, the `e.texture.release` function is not passable through IPC).
await new Promise(resolve => setTimeout(resolve, 50))
// You can send the native texture handle to native code for importing into your rendering pipeline.
// Read more at https://github.com/electron/electron/blob/main/shell/browser/osr/README.md
// importTextureHandle(dirty, e.texture.textureInfo)
// You must call `e.texture.release()` as soon as possible, before the underlying frame pool is drained.
e.texture.release()
}
})
win.loadURL('https://github.com')
事件: 'devtools-reload-page'
当 devtools 窗口指示 webContents 重新加载时触发
事件: 'will-attach-webview'
返回
event
事件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'
返回
details
事件<>message
字符串 - 消息文本level
字符串 - 消息严重性。 可能的值包括info
、warning
、error
和debug
。lineNumber
整数 - 日志源中的行号sourceId
字符串 - 日志源的 URLframe
WebFrameMain - 记录消息的框架
level
整数 Deprecated - 日志级别,从 0 到 3。 按照顺序,它与verbose
、info
、warning
和error
匹配。message
字符串 Deprecated - 实际的控制台消息line
Integer 已弃用 - 触发此控制台消息的源代码的行号sourceId
string 已弃用
当关联的窗口记录控制台消息时发出。
事件:'preload-error'
返回
event
事件preloadPath
stringerror
Error
当预加载脚本 preloadPath
抛出未处理的异常 error
时发出。
事件:'ipc-message'
返回
event
IpcMainEventchannel
string...args
any[]
当渲染器进程通过 ipcRenderer.send()
发送异步消息时发出。
另请参见 webContents.ipc
,它提供了一个 IpcMain
-like 接口,用于专门响应来自此 WebContents 的 IPC 消息。
事件:'ipc-message-sync'
返回
event
IpcMainEventchannel
string...args
any[]
当渲染器进程通过 ipcRenderer.sendSync()
发送同步消息时发出。
另请参见 webContents.ipc
,它提供了一个 IpcMain
-like 接口,用于专门响应来自此 WebContents 的 IPC 消息。
事件:'preferred-size-changed'
返回
event
事件preferredSize
Size - 包含文档布局所需的最小尺寸,而无需滚动。
当 WebContents
的首选尺寸发生更改时发出。
仅当在 webPreferences
中将 enablePreferredSizeMode
设置为 true
时,才会发出此事件。
事件:'frame-created'
返回
event
事件details
对象frame
WebFrameMain | null - 创建的帧。 如果在帧已导航或被销毁后访问,则可能为null
。
当 mainFrame、<iframe>
或嵌套的 <iframe>
加载到页面中时发出。
实例方法
contents.loadURL(url[, options])
url
字符串
返回 Promise<void>
- 当页面完成加载时,promise 将解析(请参阅 did-finish-load
),如果页面加载失败,则拒绝(请参阅 did-fail-load
)。 已经附加了一个 noop 拒绝处理程序,可以避免未处理的拒绝错误。
在窗口中加载 url
。 url
必须包含协议前缀,例如 http://
或 file://
。 如果加载应绕过 http 缓存,则使用 pragma
标头来实现。
const win = new BrowserWindow()
const options = { extraHeaders: 'pragma: no-cache\n' }
win.webContents.loadURL('https://github.com', options)
contents.loadFile(filePath[, options])
filePath
string
返回 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
字符串
启动对 url
处资源的下载,而不进行导航。 将触发 session
的 will-download
事件。
contents.getURL()
返回 string
- 当前网页的 URL。
const { BrowserWindow } = require('electron')
const win = new BrowserWindow({ width: 800, height: 600 })
win.loadURL('https://github.com').then(() => {
const currentURL = win.webContents.getURL()
console.log(currentURL)
})
contents.getTitle()
返回 string
- 当前网页的标题。
contents.isDestroyed()
返回 boolean
- 网页是否已销毁。
contents.close([opts])
opts
Object (可选)waitForBeforeUnload
boolean - 如果为 true,则在关闭页面之前触发beforeunload
事件。 如果页面阻止卸载,则 WebContents 将不会关闭。 如果页面请求阻止卸载,则将触发will-prevent-unload
。
关闭页面,就像 Web 内容调用了 window.close()
一样。
如果页面已成功关闭(即,页面未阻止卸载,或者 waitForBeforeUnload
为 false 或未指定),则 WebContents 将被销毁且不再可用。 将发出 destroyed
事件。
contents.focus()
聚焦网页。
contents.isFocused()
返回 boolean
- 网页是否已聚焦。
contents.isLoading()
返回 boolean
- 网页是否仍在加载资源。
contents.isLoadingMainFrame()
返回 boolean
- 主框架(而不仅仅是其中的 iframe 或 frame)是否仍在加载。
contents.isWaitingForResponse()
返回 boolean
- 网页是否正在等待页面主要资源的首次响应。
contents.stop()
停止任何挂起的导航。
contents.reload()
重新加载当前网页。
contents.reloadIgnoringCache()
重新加载当前页面并忽略缓存。
contents.canGoBack()
已弃用
历史
返回 boolean
- 浏览器是否可以返回到上一个网页。
已弃用:应使用新的 contents.navigationHistory.canGoBack
API。
contents.canGoForward()
已弃用
历史
返回 boolean
- 浏览器是否可以前进到下一个网页。
已弃用:应使用新的 contents.navigationHistory.canGoForward
API。
contents.canGoToOffset(offset)
已弃用
历史
offset
Integer
返回 boolean
- 网页是否可以转到 offset
。
已弃用:应使用新的 contents.navigationHistory.canGoToOffset
API。
contents.clearHistory()
已弃用
历史
清除导航历史记录。
已弃用:应使用新的 contents.navigationHistory.clear
API。
contents.goBack()
已弃用
历史
使浏览器返回一个网页。
已弃用:应使用新的 contents.navigationHistory.goBack
API。
contents.goForward()
已弃用
历史
使浏览器前进一个网页。
已弃用:应使用新的 contents.navigationHistory.goForward
API。
contents.goToIndex(index)
已弃用
历史
index
Integer
将浏览器导航到指定的绝对网页索引。
已弃用:应使用新的 contents.navigationHistory.goToIndex
API。
contents.goToOffset(offset)
已弃用
历史
offset
Integer
导航到距“当前条目”指定的偏移量。
已弃用:应使用新的 contents.navigationHistory.goToOffset
API。
contents.isCrashed()
返回 boolean
- 渲染器进程是否崩溃。
contents.forcefullyCrashRenderer()
强制终止当前托管此 webContents
的渲染器进程。 这将导致发出 render-process-gone
事件,其中 reason=killed || reason=crashed
。 请注意,某些 webContents 共享渲染器进程,因此调用此方法也可能导致其他 webContents 的宿主进程崩溃。
在此方法之后立即调用 reload()
将强制在新的进程中进行重新加载。 当此进程不稳定或不可用时,应使用此方法,例如为了从 unresponsive
事件中恢复。
const win = new BrowserWindow()
win.webContents.on('unresponsive', async () => {
const { response } = await dialog.showMessageBox({
message: 'App X has become unresponsive',
title: 'Do you want to try forcefully reloading the app?',
buttons: ['OK', 'Cancel'],
cancelId: 1
})
if (response === 0) {
win.webContents.forcefullyCrashRenderer()
win.webContents.reload()
}
})
contents.setUserAgent(userAgent)
userAgent
string
覆盖此网页的用户代理。
contents.getUserAgent()
返回 string
- 此网页的用户代理。
contents.insertCSS(css[, options])
css
string
返回 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
stringuserGesture
boolean (可选) - 默认为false
。
返回 Promise<any>
- 一个 promise,它解析为已执行代码的结果,如果代码的结果是被拒绝的 promise,则会被拒绝。
在页面中评估 code
。
在浏览器窗口中,某些 HTML API(如 requestFullScreen
)只能由用户的交互手势调用。 将 userGesture
设置为 true
将消除此限制。
代码执行将被暂停,直到网页停止加载。
const win = new BrowserWindow()
win.webContents.executeJavaScript('fetch("https://jsonplaceholder.typicode.com/users/1").then(resp => resp.json())', true)
.then((result) => {
console.log(result) // Will be the JSON object from the fetch call
})
contents.executeJavaScriptInIsolatedWorld(worldId, scripts[, userGesture])
worldId
Integer - 运行 javascript 的世界的 ID,0
是默认世界,999
是 Electron 的contextIsolation
功能使用的世界。 你可以在这里提供任何整数。scripts
WebSource[]userGesture
boolean (可选) - 默认为false
。
返回 Promise<any>
- 一个 promise,它解析为已执行代码的结果,如果代码的结果是被拒绝的 promise,则会被拒绝。
与 executeJavaScript
类似,但在隔离的上下文中评估 scripts
。
contents.setIgnoreMenuShortcuts(ignore)
ignore
boolean
当此 Web 内容处于焦点时,忽略应用程序菜单快捷键。
contents.setWindowOpenHandler(handler)
-
handler
Function<WindowOpenHandlerResponse>details
对象url
string - 传递给window.open()
的 URL 的已解析版本。 例如,使用window.open('foo')
打开窗口将产生类似https://the-origin/the/current/path/foo
的结果。frameName
string -window.open()
中提供的窗口名称features
string - 提供给window.open()
的以逗号分隔的窗口功能列表。disposition
字符串 - 可以是default
、foreground-tab
、background-tab
、new-window
或other
。referrer
引用器 - 将传递到新窗口的引用器。 可能不会导致发送Referer
标头,具体取决于引用器策略。postBody
PostBody(可选) - 将发送到新窗口的 post 数据,以及将设置的相应标头。 如果没有要发送的 post 数据,则该值将为null
。 仅在窗口由设置了target=_blank
的表单创建时定义。
返回
WindowOpenHandlerResponse
- 设置为{ action: 'deny' }
会取消创建新窗口。{ action: 'allow' }
将允许创建新窗口。 返回无法识别的值(例如 null、未定义或没有可识别的“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
numbermaximumLevel
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
Integery
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)
按照给定的偏移量调整焦点帧中的当前文本选择的起始和结束点。 负数表示将选择向文档的开头移动,正数表示将选择向文档的结尾移动。
示例
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 - 要搜索的内容,不能为空。
Returns Integer
- 用于请求的请求 ID。
启动一个请求以查找网页中 text
的所有匹配项。 可以通过订阅 found-in-page
事件来获得请求的结果。
contents.stopFindInPage(action)
action
string - 指定结束webContents.findInPage
请求时要执行的操作。clearSelection
- 清除选择。keepSelection
- 将选择转换为普通选择。activateSelection
- 聚焦并单击选择的节点。
使用提供的 action
停止任何 findInPage
请求。
const win = new BrowserWindow()
win.webContents.on('found-in-page', (event, result) => {
if (result.finalUpdate) win.webContents.stopFindInPage('clearSelection')
})
const requestId = win.webContents.findInPage('api')
console.log(requestId)
contents.capturePage([rect, opts])
rect
Rectangle (可选) - 要捕获的页面的区域。opts
Object (可选)stayHidden
boolean (可选) - 使页面保持隐藏而不是可见。 默认为false
。stayAwake
boolean (可选) - 保持系统唤醒而不是允许其进入睡眠状态。 默认为false
。
返回 Promise<NativeImage>
- 解析为 NativeImage
捕获 rect
内页面的快照。 省略 rect
将捕获整个可见页面。 当页面的浏览器窗口隐藏并且捕获计数不为零时,该页面被认为是可见的。 如果您希望页面保持隐藏状态,则应确保将 stayHidden
设置为 true。
contents.isBeingCaptured()
Returns boolean
- 是否正在捕获此页面。 当捕获计数大于 0 时,它返回 true。
contents.getPrintersAsync()
获取系统打印机列表。
返回 Promise<PrinterInfo[]>
- 解析为 PrinterInfo[]
contents.print([options], [callback])
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)
返回 Promise<Buffer>
- 解析为生成的 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 的一个示例
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])
打开 devtools。
当 contents
是一个 <webview>
标签时,mode
默认为 detach
,显式传递一个空的 mode
可以强制使用上次使用的停靠状态。
在 Windows 上,如果启用了 Windows 控制叠加层,则 Devtools 将以 mode: 'detach'
打开。
contents.closeDevTools()
关闭 devtools。
contents.isDevToolsOpened()
Returns boolean
- devtools 是否已打开。
contents.isDevToolsFocused()
Returns boolean
- devtools 视图是否已聚焦。
contents.getDevToolsTitle()
返回 string
- DevTools 窗口的当前标题。 只有在 DevTools 以 undocked
或 detach
模式打开时才可见。
contents.setDevToolsTitle(title)
title
字符串
将 DevTools 窗口的标题更改为 title
。 只有在 DevTools 以 undocked
或 detach
模式打开时才可见。
contents.toggleDevTools()
切换开发者工具。
contents.inspectElement(x, y)
x
Integery
Integer
开始检查位置 (x
, y
) 处的元素。
contents.inspectSharedWorker()
打开共享工作线程上下文的开发者工具。
contents.inspectSharedWorkerById(workerId)
workerId
string
根据 ID 检查共享工作线程。
contents.getAllSharedWorkers()
返回 SharedWorkerInfo[] - 有关所有共享工作线程的信息。
contents.inspectServiceWorker()
打开服务工作线程上下文的开发者工具。
contents.send(channel, ...args)
channel
string...args
any[]
通过 channel
向渲染器进程发送一个异步消息,以及参数。 参数将使用 结构化克隆算法 进行序列化,就像 postMessage
一样,因此不包含原型链。 发送函数、Promise、符号、WeakMap 或 WeakSet 将抛出异常。
发送非标准的 JavaScript 类型(例如 DOM 对象或特殊的 Electron 对象)将抛出异常。
有关更多阅读,请参阅 Electron 的 IPC 指南。
contents.sendToFrame(frameId, channel, ...args)
frameId
Integer | [number, number] - 要发送到的帧的 ID,如果帧与主帧位于不同的进程中,则为[processId, frameId]
对。channel
string...args
any[]
通过 channel
向渲染器进程中的特定帧发送一个异步消息,以及参数。 参数将使用 结构化克隆算法 进行序列化,就像 postMessage
一样,因此不包含原型链。 发送函数、Promise、符号、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
stringmessage
anytransfer
MessagePortMain[] (可选)
向渲染器进程发送消息,可以选择性地转移零个或多个 MessagePortMain
对象的所有权。
通过访问发出的事件的 ports
属性,转移的 MessagePortMain
对象将在渲染器进程中可用。 当它们到达渲染器时,它们将是原生的 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
ObjectscreenPosition
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
函数image
NativeImagedirtyRect
Rectangle
开始订阅演示事件和捕获的帧,当有演示事件时,将使用 callback(image, dirtyRect)
调用 callback
。
image
是 NativeImage 的一个实例,用于存储捕获的帧。
dirtyRect
是一个包含 x, y, width, height
属性的对象,用于描述页面上重新绘制的部分。如果 onlyDirty
设置为 true
,则 image
将仅包含重新绘制的区域。onlyDirty
默认为 false
。
contents.endFrameSubscription()
结束订阅帧呈现事件。
contents.startDrag(item)
item
对象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 所在的窗口的完整内容。
如果启用了离屏渲染,则使帧失效,并通过 'paint'
事件生成一个新帧。
contents.getWebRTCIPHandlingPolicy()
返回 string
- 返回 WebRTC IP 处理策略。
contents.setWebRTCIPHandlingPolicy(policy)
policy
string - 指定 WebRTC IP 处理策略。default
- 公开用户的公共和本地 IP。这是默认行为。使用此策略时,WebRTC 有权枚举所有接口并绑定它们以发现公共接口。default_public_interface_only
- 公开用户的公共 IP,但不公开用户的本地 IP。使用此策略时,WebRTC 应仅使用 http 使用的默认路由。这不会公开任何本地地址。default_public_and_private_interfaces
- 公开用户的公共和本地 IP。使用此策略时,WebRTC 应仅使用 http 使用的默认路由。这也公开了相关的默认私有地址。默认路由是 OS 在多宿主端点上选择的路由。disable_non_proxied_udp
- 不公开公共或本地 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
对象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
。可以与帧特定导航事件(例如 did-frame-navigate
)传递的 frameProcessId
进行比较。
contents.takeHeapSnapshot(filePath)
filePath
string - 输出文件的路径。
返回 Promise<void>
- 指示是否已成功创建快照。
拍摄 V8 堆快照并将其保存到 filePath
。
contents.getBackgroundThrottling()
返回 boolean
- 当页面变为后台时,此 WebContents 是否会限制动画和计时器。这也会影响页面可见性 API。
contents.setBackgroundThrottling(allowed)
allowed
boolean
控制当页面变为后台时,此 WebContents 是否会限制动画和计时器。这也会影响页面可见性 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
只读
一个 IpcMain
,其作用域仅限于从此 WebContents 发送的 IPC 消息。
使用 ipcRenderer.send
、ipcRenderer.sendSync
或 ipcRenderer.postMessage
发送的 IPC 消息将按以下顺序传递
contents.on('ipc-message')
contents.mainFrame.on(channel)
contents.ipc.on(channel)
ipcMain.on(channel)
将按以下顺序检查使用 invoke
注册的处理程序。将调用定义的第一个处理程序,其余处理程序将被忽略。
contents.mainFrame.handle(channel)
contents.handle(channel)
ipcMain.handle(channel)
在 WebContents 上注册的处理程序或事件侦听器将接收从任何帧发送的 IPC 消息,包括子帧。在大多数情况下,只有主帧可以发送 IPC 消息。但是,如果启用了 nodeIntegrationInSubFrames
选项,则子帧也可以发送 IPC 消息。在这种情况下,处理程序应检查 IPC 事件的 senderFrame
属性,以确保消息来自预期的帧。或者,使用 WebFrameMain.ipc
接口直接在相应的帧上注册处理程序。
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
一个 boolean
属性,用于确定当页面变为后台时,此 WebContents 是否会限制动画和计时器。这也会影响页面可见性 API。
contents.mainFrame
只读
一个 WebFrameMain
属性,表示页面帧层次结构的顶层帧。
contents.opener
只读
一个 WebFrameMain | null
属性,表示打开此 WebContents 的帧,无论是通过 open() 还是通过导航带有 target 属性的链接。
contents.focusedFrame
只读
一个 WebFrameMain | null
属性,表示此 WebContents 中当前聚焦的帧。可以是顶层帧、内部 <iframe>
,如果未聚焦任何内容,则为 null
。