跳转到主内容

webContents

渲染以及控制 web 页面

进程:主进程

webContents是一个EventEmitter. 负责渲染和控制网页, 是 BrowserWindow 对象的一个属性。 这是一个访问 webContents 对象的例子:

const { BrowserWindow } = require('electron')

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

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

方法

通过webContents模块可以访问以下方法:

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

webContents.getAllWebContents()

返回 WebContents[] - 所有 WebContents 实例的数组。 包含所有Windows,webviews,opened devtools 和 devtools 扩展背景页的 web 内容

webContents.getFocusedWebContents()

Returns WebContents | null - The web contents that is focused in this application, otherwise returns null.

webContents.fromId(id)

  • id Integer

返回 WebContents | undefined - 一个指定 ID 的 WebContents 实例,如果没有找到指定 ID 相关联的 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 webContents.fromDevToolsTargetId(targetId)
}

类: WebContents

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

Process: Main
此类不从 'electron' 模块导出. 它只能作为Electron API中其他方法的返回值。

实例事件

Event: 'did-finish-load'

导航完成时触发,即选项卡的旋转器将停止旋转,并指派onload事件后。

Event: 'did-fail-load'

返回:

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

这个事件类似于 did-finish-load ,只不过是在加载失败之后触发。 完整的错误码列表以及含义,请看这

Event: 'did-fail-provisional-load'

返回:

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

这个事件类似于 did-finish-load,只不过是在加载失败或取消加载之后触发,例如调用 window.stop()

Event: 'did-frame-finish-load'

返回:

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

当框架完成导航(navigation)时触发

Event: 'did-start-loading'

当tab中的旋转指针(spinner)开始旋转时,就会触发该事件。

Event: 'did-stop-loading'

当tab中的旋转指针(spinner)结束旋转时,就会触发该事件。

事件: 'dom-ready'

返回:

  • event Event

当顶级 frame 的 document 被加载完时触发。

事件: 'page-title-updated'

返回:

  • event Event
  • title string
  • explicitSet boolean

当导航时页面标题更新时触发。 当标题从文件 url 中合成时 explicitSet 为 false。

事件: 'page-favicon-updated'

返回:

  • event Event
  • favicons string[] - 由连接组成的数组。

当页面获取到favicon的连接时,触发该事件。

Event: 'new-window' 已弃用

返回:

  • event NewWindowWebContentsEvent
  • url string
  • frameName string
  • disposition string - 可以被设置为 default, foreground-tab, background-tab, new-window, save-to-diskother.
  • options BrowserWindowConstructorOptions - 用于创建新的 BrowserWindow.
  • additionalFeatures string[] - 提供给 window.open() 非标准功能 (不是由 Chromium 或 Electron 提供) 。 已弃用,同时现将设置为空数组 []
  • referrer Referrer - referrer 将传到新窗口。 可能会也可能不会发送 Referer 头,取决于 referrer 策略。
  • postBody PostBody (可选) - post 数据发送至新窗口,以及设置适当的请求头(headers)。 如果没有 post 数据被发送,值将为 null。 仅当窗口从 form 并设置 target=_blank 时创建,才会被定义。

已弃用,赞成使用webContents.setWindowOpenHandler

当页面为 url 请求打开一个新窗口时触发。 可能由 window.open 或 类似 <a target='_blank'> 外链触发。

默认情况下, 将为 url 创建新的 BrowserWindow

调用event.preventDefault()事件,可以阻止Electron自动创建新的BrowserWindow实例。 调用event.preventDefault() 事件后,你还可以手动创建新的BrowserWindow实例,不过接下来你必须用event.newGuest方法来引用BrowserWindow实例,如果你不这样做,则可能会产生异常。 例如:

myBrowserWindow.webContents.on('new-window', (event, url, frameName, disposition, options, additionalFeatures, referrer, postBody) => {
event.preventDefault()
const win = new BrowserWindow({
webContents: options.webContents, // use existing webContents if provided
show: false
})
win.once('ready-to-show', () => win.show())
if (!options.webContents) {
const loadOptions = {
httpReferrer: referrer
}
if (postBody != null) {
const { data, contentType, boundary } = postBody
loadOptions.postData = postBody.data
loadOptions.extraHeaders = `content-type: ${contentType}; boundary=${boundary}`
}

win.loadURL(url, loadOptions) // existing webContents will be navigated automatically
}
event.newGuest = win
})

Event: '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 将传到新窗口。 可能会也可能不会发送Referer 头,取决于 referrer 策略。
    • postBody PostBody (可选) - post 数据发送至新窗口,以及设置适当的请求头(headers)。 如果没有 post 数据被发送,值将为 null。 仅当窗口从 form 并设置 target=_blank 时创建,才会被定义。
    • disposition string - 可以是 default, foreground-tab, background-tab, new-window, save-to-diskother.

在渲染进程中由 window.open 成功创建窗口之后 触发。 如果创建窗口在 webContents.setWindowOpenHandler 中取消,则不会触发。

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

Event: 'will-navigate'

返回:

  • event Event
  • url string

当用户或页面想要导航时触发。 它可能发生在 window.location 对象改变或用户点击页面上的链接时,可能会发生这种情况。

当使用如 webContents.loadURLwebContents.back APIs 以编程方式导航时,将不会触发此事件。

页面内导航也不会触发,例如点击锚点或更新 window.location.hash。 可使用 did-navigate-in-page 事件。

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

Event: 'did-start-navigation'

返回:

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

当任何 frame (包括 main) 开始导航时触发。 当页面内导航 isInPlacetrue

Event: 'will-redirect'

返回:

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

当一个服务器端的重定向导航时触发。 例如,302 重定向。

事件在 did-start-navigation 之后,总是在 did-redirect-navigation 之前触发。

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

Event: 'did-redirect-navigation'

返回:

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

导航期间发生服务端重定向之后后触发。 例如,302 重定向。

这个事件不能被阻止,如果你想要阻止重定向,你应该在 will-redirect 事件之中处理。

Event: 'did-navigate'

返回:

  • event Event
  • url string
  • httpResponseCode Integer - -1 代表非 HTTP 导航。
  • httpStatusText string - 非 HTTP 导航为空。

当 main frame 导航完成时触发。

事件在页面内导航不会触发,例如点击锚点或更新 window.location.hash。 可使用 did-navigate-in-page 事件。

Event: 'did-frame-navigate'

返回:

  • event Event
  • url string
  • httpResponseCode Integer - -1 代表非 HTTP 导航。
  • httpStatusText string - 空代表非 HTTP 导航。
  • isMainFrame boolean
  • frameProcessId Integer
  • frameRoutingId Integer

当任意 frame 导航完成后触发。

事件在页面内导航不会触发,例如点击锚点或更新 window.location.hash。 可使用 did-navigate-in-page 事件。

Event: 'did-navigate-in-page'

返回:

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

页面内任意 frame 发生导航时触发。

当发生页内导航时,虽然页面地址发生变化,但它并没有导航到其它页面。 例如,点击锚点链接,或者DOM的 hashchange事件被触发时,都会触发该事件。

Event: 'will-prevent-unload'

返回:

  • event Event

beforeunload 事件尝试取消页面 unload 时触发。

调用 event.preventDefault() 将忽略 beforeunload 事件处理,同时允许页面 卸载(unloaded)。

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 的每一个 规范 联系起来。

Event: 'crashed' 已弃用

返回:

  • event Event
  • killed boolean

当渲染进程崩溃或被结束时触发

已废弃: 此事件被包含更多关于渲染过程为何消失的信息的 render-process-gone 事件替代了 并不总是因为崩溃而触发。 当你换用child-process-gone事件时,原事件的 killed 布尔值可以被 reason === 'killed' 取代。

事件: 'render-process-gone'

返回:

  • event Event
  • details Object
    • reason string - 渲染进程消失的原因。 可选值:
      • clean-exit - 以零为退出代码退出的进程
      • abnormal-exit - 以非零退出代码退出的进程
      • killed - 进程发送一个SIGTERM,否则是被外部杀死的。
      • crashed - 进程崩溃
      • oom - 进程内存不足
      • launch-failed - 进程从未成功启动
      • integrity-failure - 窗口代码完整性检查失败
    • exitCode Integer - 进程的退出代码,除非在 reasonlaunch-failed 的情况下, exitCode 将是一个平台特定的启动失败错误代码。

渲染器进程意外消失时触发。 这种情况通常因为进程崩溃或被杀死。

事件: 'unresponsive'

网页变得未响应时触发

事件: 'responsive'

未响应的页面变成响应时触发

Event: 'plugin-crashed'

返回:

  • event Event
  • name string
  • version string

当有插件进程崩溃时触发

Event: 'destroyed'

webContents被销毁时,触发该事件。

Event: 'before-input-event'

返回:

在页面中调度 keydownkeyup 之前触发。 调用 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) => {
// 例如, 当 Ctrl/Cmd are down 被按下,仅开启应用程序菜单键盘快捷键。
win.webContents.setIgnoreMenuShortcuts(!input.control && !input.meta)
})

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

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

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

窗口离开由HTML API触发的全屏状态时触发

Event: 'zoom-changed'

返回:

  • event Event
  • zoomDirection string - 可以是 inout.

当用户使用鼠标中键请求改变缩放等级时触发。

事件: 'blur'

WebContents 失去焦点时触发。

事件: 'focus'

WebContents 获得焦点时触发。

请注意,在 macOS 上,有焦点意味着 WebContents 是窗口的第一响应者,因为每个窗口的第一响应者不会更改,所以在窗口之间切换焦点是不会出发 WebContentsfocusblur 事件的。

WebContentsfocusblur 事件应该仅用于检测同一窗口中不同 WebContentsBrowserView 之间的焦点变化。

Event: 'devtools-opened'

当开发者工具被打开时,触发该事件。

Event: 'devtools-closed'

当开发者工具被关闭时,触发该事件。

Event: 'devtools-focused'

当开发者工具被选中/打开时,触发该事件。

事件: 'certificate-error'

返回:

  • event Event
  • url string
  • error string - 错误码。
  • certificate 证书
  • callback Function
    • isTrusted boolean - 表示证书是否视为可信任的。
  • isMainFrame boolean

证书链接验证失败时,触发该事件。

使用方式与appcertificate-error的事件相同。

事件: 'select-client-certificate'

返回:

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

当一个客户证书被请求的时候发出。

使用方式与appselect-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 要进行基本身份验证时触发。

使用方式与applogin的事件相同。

Event: 'found-in-page'

返回:

  • event Event
  • result Object
    • requestId Integer
    • activeMatchOrdinal Integer - 当前匹配位置。
    • matches Integer - 符合匹配条件的元素个数。
    • selectionArea Rectangle - 第一个匹配到区域的坐标。
    • finalUpdate boolean

如果调用[webContents.findInPage]有返回时,会触发这一事件。

Event: 'media-started-playing'

多媒体开始播放时,触发该事件。

Event: 'media-paused'

当媒体文件暂停或播放完成的时候触发

Event: 'did-change-theme-color'

返回:

  • event Event
  • color (string | null) - 主题颜色格式为 '#rrggbb'。 没有设置主题颜色时为 null

页面主页颜色改变时触发。 通常是由于遇到 meta 标签:

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

Event: 'update-target-url'

返回:

  • event Event
  • url string

当鼠标滑到,或者键盘切换到a连接时,触发该事件。

Event: 'cursor-changed'

返回:

  • event Event
  • type string
  • image NativeImage (可选)
  • scale Float (可选) - 自定义鼠标指针的缩放比例系数。
  • size Size (可选) - image大小。
  • hotspot Point (可选) - 自定义鼠标指针热点的坐标。

当鼠标指针改变的时候触发。 Type参数值包含:default, crosshair, pointer, 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, 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, grabbingcustom.

关于自定义鼠标指针,如果 type 参数是 custom, image 保存 NativeImage 自定义鼠标指定图片,scale, size and hotspot 将保存在附加信息中。

Event: 'context-menu'

返回:

  • event Event
  • params Object
    • x Integer - x 坐标。
    • y Integer - y 坐标。
    • frame WebFrameMain - 右键菜单被调用的 Frame。
    • linkURL string - URL of the link that encloses the node the context menu was invoked on.
    • linkText string - Text associated with the link. 如果链接的内容是图片,则可能为空的 string。
    • pageURL string - URL of the top level page that the context menu was invoked on.
    • frameURL string - URL of the subframe that the context menu was invoked on.
    • srcURL string - Source URL for the element that the context menu was invoked on. Elements 源 URLs 是 图片、音频 和 视频。
    • mediaType string - Type of the node the context menu was invoked on. 可以是 none, image, audio, video, canvas, fileplugin
    • hasImageContents boolean - Whether the context menu was invoked on an image which has non-empty contents.
    • isEditable boolean - Whether the context is editable.
    • selectionText string - Text of the selection that the context menu was invoked on.
    • titleText string - Title text of the selection that the context menu was invoked on.
    • altText string - Alt text of the selection that the context menu was invoked on.
    • suggestedFilename string - Suggested filename to be used when saving file through 'Save Link As' option of context menu.
    • selectionRect Rectangle - Rect 代表选中区域的坐标。
    • selectionStartOffset number - Start position of the selection text.
    • referrerPolicy Referrer - 调用菜单 frame 的 referrer policy。
    • misspelledWord string - The misspelled word under the cursor, if any.
    • dictionarySuggestions string[] - An array of suggested words to show the user to replace the misspelledWord. 仅当单词拼写错误且启用了拼写检查器时可用。
    • frameCharset string - The character encoding of the frame on which the menu was invoked.
    • inputFieldType string - If the context menu was invoked on an input field, the type of that field. 值可能为 noneplainTextpasswordother
    • spellcheckEnabled boolean - If the context is editable, whether or not spellchecking is enabled.
    • menuSourceType string - Input source that invoked the context menu. 可以是 nonemousekeyboardtouchtouchMenulongPresslongTaptouchHandlestylusadjustSelectionadjustSelectionReset
    • mediaFlags Object - 调用菜单的媒体 element 的标志。
      • inError boolean - Whether the media element has crashed.
      • isPaused boolean - Whether the media element is paused.
      • isMuted boolean - Whether the media element is muted.
      • hasAudio boolean - Whether the media element has audio.
      • isLooping boolean - Whether the media element is looping.
      • isControlsVisible boolean - Whether the media element's controls are visible.
      • canToggleControls boolean - Whether the media element's controls are toggleable.
      • canPrint boolean - Whether the media element can be printed.
      • canSave boolean - Whether or not the media element can be downloaded.
      • canShowPictureInPicture boolean - Whether the media element can show picture-in-picture.
      • isShowingPictureInPicture boolean - Whether the media element is currently showing picture-in-picture.
      • canRotate boolean - Whether the media element can be rotated.
      • canLoop boolean - Whether the media element can be looped.
    • editFlags Object - 这些标志表示渲染进程是否认为能够执行相应操作行为。
      • canUndo boolean - Whether the renderer believes it can undo.
      • canRedo boolean - Whether the renderer believes it can redo.
      • canCut boolean - Whether the renderer believes it can cut.
      • canCopy boolean - Whether the renderer believes it can copy.
      • canPaste boolean - Whether the renderer believes it can paste.
      • canDelete boolean - Whether the renderer believes it can delete.
      • canSelectAll boolean - Whether the renderer believes it can select all.
      • canEditRichly boolean - Whether the renderer believes it can edit text richly.

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

事件: 'select-bluetooth-device'

返回:

navigator.bluetooth.requestDevice 调用时选择蓝牙设备时触发。 使用 navigator.bluetooth api 需要启动 webBluetooth 。 如果未调用 event.preventDefault ,将选择 第一个可用设备。 callback 应用传入被选择的 deviceId,传入空 string 到 callback 将取消请求。

如果没有为该事件添加监听,所有蓝牙请求将被取消。

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

let win = null
app.commandLine.appendSwitch('enable-experimental-web-platform-features')

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) {
callback('')
} else {
callback(result.deviceId)
}
})
})

Event: 'paint'

返回:

当一个新的帧被创建时触发。 buffer 中仅传入脏区(dirty area)。

const { BrowserWindow } = require('electron')

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

Event: 'devtools-reload-page'

当在开发者工具中命令webContents重新加载时,触发该事件。

Event: 'will-attach-webview'

返回:

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

<webview> 的 web contents 开始附加到当前 web contents 时触发。 调用 event.preventDefault() 将销毁访客页面。

此事件可以用来在加载前为 <webview>webContents 配置 webPreferences,并提供设置无法通过 <webview> 属性设置的功能。

Event: 'did-attach-webview'

返回:

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

<webview>被挂载到页面内容中时,触发该事件。

Event: 'console-message'

返回:

  • event Event
  • level Integer - 日志级别,从0到3。 按顺序匹配 verbose, info, warningerror.
  • message string - 实际控制台消息
  • line Integer - 触发控制台消息的源代码行号。
  • sourceId string

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

Event: 'preload-error'

返回:

  • event Event
  • preloadPath string
  • error Error

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

Event: 'ipc-message'

返回:

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

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

Event: 'ipc-message-sync'

返回:

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

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

Event: 'preferred-size-changed'

返回:

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

WebContents preferred size 改变时触发。

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

Event: 'frame-created'

返回:

  • event Event
  • details Object
    • frame WebFrameMain

mainFrame<iframe>,或是嵌套 <iframe> 在页面中被加载时触发。

实例方法

contents.loadURL(url[, options])

  • url string
  • options Object (可选)
    • httpReferrer (string | Referrer) (可选) - 一个 HTTP Referrer url。
    • userAgent string (可选) - 发起请求的 userAgent.
    • extraHeaders string (可选) - 通过"\n" 分隔的额外 headers。
    • postData (UploadRawData | UploadFile)[] (可选)
    • baseURLForDataURL string (可选) - 要加载的数据文件的根 url(带有路径分隔符). 只有当指定的 url是一个数据 url 并需要加载其他文件时,才需要这样做。

返回 Promise<void> - 当页面加载完成,promise 将被 resolve (参考 did-finish-load),如果页面加载失败,将 rejects (参考 did-fail-load). 附加一个无操作的 rejection 处理。可以避免 rejection 未处理错误。

在窗口中加载 urlurl 必须包括协议前缀,例如: http://file://。 如果加载需要绕过 http 缓存,则使用 pragma 头达到效果。

const { webContents } = require('electron')
const options = { extraHeaders: 'pragma: no-cache\n' }
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 将会resolve (见 did-finish-load),如果页面加载失败,则 reject (见 did-fail-load)。

在窗口中加载指定文件,filePath 必须是一个相对于你的应用程序根目录的 HTML 文件路径。 例如,像如下应用程序目录结构:

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

需要运行以下代码:

win.loadFile('src/index.html')

contents.downloadURL(url)

  • url string

Initiates a download of the resource at url without navigating. sessionwill-download 事件将被触发。

contents.getURL()

返回 string - 当前网页的 URL。

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

contents.getTitle()

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

contents.isDestroyed()

返回 boolean - 网面是否被销毁。

contents.focus()

页面聚焦

contents.isFocused()

返回 boolean - 网页是否具有焦点。

contents.isLoading()

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

contents.isLoadingMainFrame()

Returns boolean - Whether the main frame (and not just iframes or frames within it) is still loading.

contents.isWaitingForResponse()

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

contents.stop()

Stops any pending navigation.

contents.reload()

刷新当前页面

contents.reloadIgnoringCache()

忽略缓存强制刷新页面

contents.canGoBack()

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

contents.canGoForward()

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

contents.canGoToOffset(offset)

  • offset Integer

Returns boolean - 浏览器是否可以跳转到 offset 页面。

contents.clearHistory()

清除定位历史。

contents.goBack()

使浏览器回退到上一个页面。

contents.goForward()

使浏览器前进到下一个页面。

contents.goToIndex(index)

  • index Integer

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

contents.goToOffset(offset)

  • offset Integer

定位到相对于“当前入口”的指定的偏移。

contents.isCrashed()

Returns boolean - Whether the renderer process has crashed.

contents.forcefullyCrashRenderer()

强制终止当前承载此 webContents 的渲染进程。 这将导致 render-process-gone 事件被触发,同时参数为 reason=killed || reason=crashed。 请注意,一些 webContents 共享渲染进程,因此调用此方法可能也会使承载自此进程的其他 webContents 崩溃。

在调用此方法后立即调用 reload() ,重新加载将强制在新进程中执行。 当进程不稳定或不可用时,为了从 unresponsive 事件中恢复,则应使用此方式。

contents.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) {
contents.forcefullyCrashRenderer()
contents.reload()
}
})

contents.setUserAgent(userAgent)

  • userAgent string

重写该页面的user agent

contents.getUserAgent()

返回 string - 当前页面的 user agent。

contents.insertCSS(css[, options])

  • css string
  • options Object (可选)
    • cssOrigin string (可选) - 可以是 'user' 或 'author' 之一。 设置插入格式的 cascade origin 。 默认为 'author'.

返回 Promise<string> - 为插入css的promise,resolves 一个 key ,在这之后可以使用 contents.removeInsertedCSS(key) 删除这个CSS。

Injects CSS into the current web page and returns a unique key for the inserted stylesheet.

contents.on('did-finish-load', () => {
contents.insertCSS('html, body { background-color: #f00; }')
})

contents.removeInsertedCSS(key)

  • key string

Returns Promise<void> - Resolves if the removal was successful.

Removes the inserted CSS from the current web page. 样式由 contents.insertCSS(css) 返回的 key 来标识。

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

contents.executeJavaScript(code[, userGesture])

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

Returns Promise<any> - A promise that resolves with the result of the executed code or is rejected if the result of the code is a rejected promise.

在页面中执行 code

在浏览器窗口中,一些HTML API(如requestFullScreen)只能是 由来自用户的手势调用。 将 userGesture 设置为 true 将删除此限制。

代码执行将被挂起,直到页面停止加载。

contents.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 的 world 的 ID,0 是默认 world, 999 是 Electron contextIsolation 的 world 特征。 You can provide any integer here.
  • scripts WebSource[]
  • userGesture boolean (可选) - 默认为 false

Returns Promise<any> - A promise that resolves with the result of the executed code or is rejected if the result of the code is a rejected promise.

Works like executeJavaScript but evaluates scripts in an isolated context.

contents.setIgnoreMenuShortcuts(ignore)

  • ignore boolean

在此有焦点的 web contents 中,忽略应用程序菜单快捷键。

contents.setWindowOpenHandler(handler)

  • handler Function<{action: 'deny'} | {action: 'allow', overrideBrowserWindowOptions?: BrowserWindowConstructorOptions}>

    • details Object
      • url string - window.open()传入的 resolved 的URL。 例如,使用 window.open('foo') 打开一个窗口,将产生类似值 https://the-origin/the/current/path/foo
      • frameName string - window.open() 提供的窗口的名称。
      • features string - window.open() 提供 逗号 分割的窗口特征列表。
      • disposition string - 可以是 default, foreground-tab, background-tab, new-window, save-to-disk or other.
      • referrer Referrer - referrer 将传到新窗口。 可能会也可能不会发送 Referer 头,取决于 referrer 策略。
      • postBody PostBody (可选) - post 数据发送至新窗口,以及设置适当的请求头(headers)。 如果没有 post 数据被发送,值将为 null。 仅当窗口从 form 并设置 target=_blank 时创建,才会被定义。

    返回 {action: 'deny'} | {action: 'allow', overrideBrowserWindowOptions?: BrowserWindowConstructorOptions} - deny 取消创建新窗口。 allow 将允许新窗口被创建。 指定 overrideBrowserWindowOptions 允许自定义创建的窗口参数。 返回无法识别的值 ,例如 null,undefined,或 一个没有 action 成员的对象, 控制同将输出错误,同时与返回 {action: 'deny'} 效果相同。

渲染进程中请求创建一个新窗口之前被掉用,例如 window.open(), 带 target="_blank" 的链接, 按shift 点击链接,或使用 <form target="_blank"> 提交一个表单。 有关更多详细信息以及如何结合 did-create-window 使用,参考 window.open()

contents.setAudioMuted(muted)

  • muted boolean

使当前页面音频静音

contents.isAudioMuted()

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

contents.isCurrentlyAudible()

Returns boolean - Whether audio is currently playing.

contents.setZoomFactor(factor)

  • factor Double - Zoom factor; default is 1.0.

Changes the zoom factor to the specified factor. Zoom factor is zoom percent divided by 100, so 300% = 3.0.

The factor must be greater than 0.0.

contents.getZoomFactor()

Returns number - the current zoom factor.

contents.setZoomLevel(level)

  • level number - 缩放等级。

更改缩放等级。 The original size is 0 and each increment above or below represents zooming 20% larger or smaller to default limits of 300% and 50% of original size, respectively. The formula for this is scale := 1.2 ^ level.

注意: Chromium 级别的缩放策略是同源的,这意味着特定域的缩放级别将传播到具有相同域的所有窗口实例。 区分窗口 URL 将使缩放操作工作在每一个窗口。

contents.getZoomLevel()

Returns number - the current zoom level.

contents.setVisualZoomLevelLimits(minimumLevel, maximumLevel)

  • minimumLevel number
  • maximumLevel number

返回 Promise<void>

设置最大和最小缩放级别。

NOTE: 在 Electron 中 Visual 缩放 默认被禁止。 重新开启,调用:

contents.setVisualZoomLevelLimits(1, 3)

contents.undo()

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

contents.redo()

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

contents.cut()

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

contents.copy()

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

contents.copyImageAt(x, y)

  • x Integer
  • y Integer

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

contents.paste()

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

contents.pasteAndMatchStyle()

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

contents.delete()

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

contents.selectAll()

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

contents.unselect()

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

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 (optional) - Whether search should be case-sensitive, defaults to false.

Returns Integer - The request id used for the request.

Starts a request to find all matches for the text in the web page. 结果可以通过订阅 found-in-page 事件获得。

contents.stopFindInPage(action)

  • action string - 指定发生在 [webContents.findInPage] 结束的行为。
    • clearSelection - Clear the selection.
    • keepSelection - Translate the selection into a normal selection.
    • activateSelection - Focus and click the selection node.

以提供的 action 停止 webContents 的任何 findInPage

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

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

contents.capturePage([rect])

  • rect Rectangle (optional) - The area of the page to be captured.

返回 Promise<NativeImage> - 完成后返回一个NativeImage

rect内捕获页面的快照。 省略 rect 将捕获整个可见页面。

contents.isBeingCaptured()

返回 boolean - 是否页面正常捕获。 当捕获器计数大于 0 时,它将返回 true。

contents.incrementCapturerCount([size, stayHidden, stayAwake])

  • size Size (可选) -捕获器的适当尺寸。
  • stayHidden boolean (可选) - 使页面保持隐藏而不是可见。
  • stayAwake boolean (可选) - 使系统保持唤醒状态,而不是让它处于睡眠状态。

将捕获器计数增加 1。 当 browser window 隐藏,且捕获器计数不为零时,该页面被视为可见。 如果你想要页面保持隐藏状态,则应确保 stayHidden 设置为 true。

这也会影响 Page Visibility API。

contents.decrementCapturerCount([stayHidden, stayAwake])

  • stayHidden boolean (可选) - 使页面保持隐藏而不是可见。
  • stayAwake boolean (可选) - 使系统保持唤醒状态,而不是让它处于睡眠状态。

将捕获器计数减 1。 当 browser window 隐藏 或 遮挡,且捕获器计数归零,该页面被设置为隐藏或遮挡状态。 如果想要减少隐藏捕获器计数,应该设置 stayHidden 为 true。

contents.getPrinters() 已废弃

获取系统打印机列表

返回 PrinterInfo[]

已废弃: 请使用新的 contents.getPrintersAsync API。

contents.getPrintersAsync()

获取系统打印机列表

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

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

  • options Object (可选)
    • silent boolean (optional) - Don't ask user for print settings. 默认值为 false.
    • printBackground boolean (optional) - Prints the background color and image of the web page. 默认值为 false.
    • deviceName string (optional) - Set the printer device name to use. Must be the system-defined name and not the 'friendly' name, e.g 'Brother_QL_820NWB' and not 'Brother QL-820NWB'.
    • color boolean (optional) - Set whether the printed web page will be in color or grayscale. 默认值为 true
    • margins Object (可选)
      • marginType string (optional) - Can be default, none, printableArea, or custom. If custom is chosen, you will also need to specify top, bottom, left, and right.
      • top number (optional) - The top margin of the printed web page, in pixels.
      • bottom number (optional) - The bottom margin of the printed web page, in pixels.
      • left number (optional) - The left margin of the printed web page, in pixels.
      • right number (optional) - The right margin of the printed web page, in pixels.
    • landscape boolean (optional) - Whether the web page should be printed in landscape mode. 默认值为 false.
    • scaleFactor number (optional) - The scale factor of the web page.
    • pagesPerSheet number (optional) - The number of pages to print per page sheet.
    • collate boolean (optional) - Whether the web page should be collated.
    • copies number (optional) - The number of copies of the web page to print.
    • pageRanges Object[] (可选) - 要打印的页面范围。 在macOS上,只有数组的第一个值被信任。
      • from number - Index of the first page to print (0-based).
      • to number - Index of the last page to print (inclusive) (0-based).
    • duplexMode string (optional) - Set the duplex mode of the printed web page. 可以是 simplexshortEdgelongEdge
    • dpi Record<string, number> (optional)
      • horizontal number (optional) - The horizontal dpi.
      • vertical number (optional) - The vertical dpi.
    • header string (optional) - string to be printed as page header.
    • footer string (optional) - string to be printed as page footer.
    • pageSize string | Size (optional) - Specify page size of the printed document. Can be A3, A4, A5, Legal, Letter, Tabloid or an Object containing height.
  • callback Function (可选)
    • success boolean - 表示调用打印成功。
    • failureReason string - 如果打印失败,则回调错误说明。

当一个自定义 pageSize 被传入,Chromium 会尝试验证 width_micronsheight_microns 指定平台的最小值。 宽度和高度必须都至少为 353 微米,但在某些操作系统上可能更高。

打印窗口的页面。 当 silent 设置为 true,如果 deviceName 为空,Electron 将采用系统默认打印机,且使用默认设置打印。

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

示例:

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)

  • 选项 对象
    • headerFooter Record<string, string> (optional) - the header and footer for the PDF.
      • title string - The title for the PDF header.
      • url string - the url for the PDF footer.
    • landscape boolean (optional) - true for landscape, false for portrait.
    • marginsType Integer (optional) - Specifies the type of margins to use. Uses 0 for default margin, 1 for no margin, and 2 for minimum margin.
    • scaleFactor number (optional) - The scale factor of the web page. Can range from 0 to 100.
    • pageRanges Record<string, number> (optional) - The page range to print.
      • from number - Index of the first page to print (0-based).
      • to number - Index of the last page to print (inclusive) (0-based).
    • pageSize string | Size (optional) - Specify page size of the generated PDF. 可以是 A3, A4, A5, Legal, Letter, Tabloid 或一个对象包含单位微米的 height and width
    • printBackground boolean (optional) - Whether to print CSS backgrounds.
    • printSelectionOnly boolean (optional) - Whether to print selection only.

返回 Promise<Buffer> - 使用生成 PDF 的数据解决。

使用 Chromium 的预览打印自定义设置,将窗口的网页打印为 PDF。

@page CSS 规则在页面使用,landscape 将被忽略。

默认情况下,空 options 将被视为:

{
marginsType: 0,
printBackground: false,
printSelectionOnly: false,
landscape: false,
pageSize: 'A4',
scaleFactor: 100
}

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

webContents.printToPDF 示例:

const { BrowserWindow } = require('electron')
const fs = require('fs')
const path = require('path')
const os = require('os')

const win = new BrowserWindow({ width: 800, height: 600 })
win.loadURL('http://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)
})
})

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> tag.

注意: 关闭 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])

  • options Object (可选)
    • mode string - 使用指定的 dock state 打开开发者工具, 可以是 left, right, bottom, undocked, detach。 默认使用上一次的 dock state。 在 undocked 模式下,可以恢复停靠。 在 detach 模式下则不能。
    • activate boolean (可选) - 是否将打开的开发者工具窗口置于前台。 默认值为 true

打开开发者工具。

contents<webview>标签时,mode将默认detach,显式传递空的mode,可以强制使用上次的 dock state.

contents.closeDevTools()

关闭开发者工具。

contents.isDevToolsOpened()

返回boolean - 开发者工具是否处于开启状态。

contents.isDevToolsFocused()

返回boolean - 开发者工具是否处于当前执行状态。

contents.toggleDevTools()

切换开发工具

contents.inspectElement(x, y)

  • x Integer
  • y Integer

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

contents.inspectSharedWorker()

以 shared worker 上下文打开开发者工具。

contents.inspectSharedWorkerById(workerId)

  • workerId string

基于 shared worker 的 ID 检查。

contents.getAllSharedWorkers()

返回 SharedWorkerInfo[] - 所有Shared Workers 的相关信息。

contents.inspectServiceWorker()

以 service worker 上下文打开开发者工具。

contents.send(channel, ...args)

  • channel string
  • ...args any[]

由经 channel 向渲染进程发送异步带参消息。 参数将使用 Structured Clone Algorithm进行序列化,就像 postMessage,因此原型链将不会包含在内。 发送 Functions, Promises, Symbols, WeakMaps, 或 WeakSets 将抛出异常

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

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

从主进程发送消息到渲染进程 示例:

// 在主进程中.
const { app, BrowserWindow } = require('electron')
let win = null

app.whenReady().then(() => {
win = new BrowserWindow({ width: 800, height: 600 })
win.loadURL(`file://${__dirname}/index.html`)
win.webContents.on('did-finish-load', () => {
win.webContents.send('ping', 'whoooooooh!')
})
})
<!-- index.html -->
<html>
<body>
<script>
require('electron').ipcRenderer.on('ping', (event, message) => {
console.log(message) // Prints 'whoooooooh!'
})
</script>
</body>
</html>

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

  • frameId Integer | [number, number] - 发送到的frame ID,或 [processId, frameId] 如果 frame 与 main frame 在不同的进程中。
  • channel string
  • ...args any[]

通过 channel 发送一个带参数的异步消息到渲染进程里指定的 frame。 参数使用 Structured Clone Algorithm 序列化,就像 postMessage,所以不包括原型链。 发送 Functions,Promises,Symbols,WeakMaps,或 WeakSets 将抛出异常。

注意: 发送非标准的 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 { port1, port2 } = new MessageChannelMain()
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,则为原始设备比例) (默认: 0)。
    • viewSize Size - 设置被模拟的视图尺寸大小(空表示不重写)。
    • scale Float - 可用空间内被模拟视图的比例 (不适用视图模式) (默认:1)。

允许设备模拟给定参数。

contents.disableDeviceEmulation()

禁止webContents.enableDeviceEmulation允许的模拟设备

contents.sendInputEvent(inputEvent)

Sends an input event to the page. 注意: BrowserWindow 包的 contents 有焦点,sendInputEvent() 才能正常工作。

contents.beginFrameSubscription([onlyDirty ,]callback)

  • onlyDirty boolean (可选) - 默认值为 false.
  • callback Function

开始订阅展现事件,同时捕获帧数据,当有一个展现事件,callback 将使用 callback(image, dirtyRect) 被调用。

image 是一个储存捕获帧的 NativeImage 实例。

dirtyRect 是一个带有 x, y, width, height 属性的对象,描述重绘的区域。 如果 onlyDirty 设置为 trueimage 仅包含重绘的区域。 onlyDirty 默认为 false

contents.endFrameSubscription()

结束订阅帧展示事件。

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

Shows pop-up dictionary that searches the selected word on the page.

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 使用的默认路由。 这也会暴露相关联的默认私有地址。 默认路由是操作系统在多宿结点上选择的路由。
    • disable_non_proxied_udp - 不暴露用户公共和本地 IP。 使用此策略时,WebRTC 应仅使用 TCP 连接他人或服务,除非代理服务器支持 UDP。

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

contents.getMediaSourceId(requestWebContents)

  • requestWebContents WebContents - Id 注册到的 Web contents。

Returns string - WebContents 流的标识。 标识可以被 navigator.mediaDevices.getUserMedia 利用 chromeMediaSource r的 tab 来使用。 该标识局限于被注册的 web contents,且仅 10 秒有效。

contents.getOSProcessId()

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

contents.getProcessId()

返回 Integer - 渲染进程关联的 Chromium 内部pid。 可以通过 frame 特定的导航事件来比较 frameProcessId (例如 did-frame-navigate)。

contents.takeHeapSnapshot(filePath)

  • filePath string - 输出文件路径

返回 Promise<void> - 指明快捷方式是否被成功创建。

获取V8堆快照并保存到 filePath

contents.getBackgroundThrottling()

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

contents.setBackgroundThrottling(allowed)

  • allowed boolean

控制当页面置于后台时,此 WebContents 是否会限制动画和计时器。 这也会影响 Page Visibility API。

contents.getType()

Returns string - webContent 的类型。 可以是 backgroundPagewindowbrowserViewremotewebviewoffscreen

contents.setImageAnimationPolicy(policy)

  • policy string - 可以是 animate, animateOncenoAnimation.

设置 webContents 的图片动画策略。 该策略仅影响 图片,当前活跃的已存在图片不受影响。 这是 Chromium 中的已知限制,您可以使用 img.src = img.src 强制图片重新计算,这结果就是没有网络请求但会更新动画策略。

这类似于,Chromium 中的辅助功能 animationPolicy

实例属性

contents.audioMuted

一个 boolean 属性,页面是否静音。

contents.userAgent

一个 string 属性,页面的 user agent。

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的唯一标识(unique ID)。 每个ID在整个Electron应用程序的所有 WebContents 实例中都是唯一的。

contents.session 只读

一个被 webContents 使用的 Session

contents.hostWebContents 只读

可能拥有些 WebContentsWebContents 实例。

contents.devToolsWebContents 只读

一个 WebContents | null 属性,表示与指定 WebContents 相关联的 DevTools 的 WebContents

注意: 永远不应该存储此对象,因为当 DevTools 关闭时,它可能会 null

contents.debugger 只读

一个 webContents 的 Debugger 实例。

contents.backgroundThrottling

一个 boolean 属性,当页面置于后台时,此 WebContents 是否会限制动画和计时器。 这也会影响 Page Visibility API。

contents.mainFrame 只读

一个 WebFrameMain 属性,代表页面 frame 结构中的顶级 frame。