Electron 中文文档 Electron webContents 模块

webContents是一个 事件发出者.

它负责渲染并控制网页，也是 BrowserWindow对象的属性.一个使用 webContents的例子:

const BrowserWindow = require('electron').BrowserWindow;
var win = new BrowserWindow({width: 800, height: 1500});
win.loadURL("https://www.w3cschool.cn");
var webContents = win.webContents;

事件

webContents对象可发出下列事件:

Event: 'did-finish-load'

当导航完成时发出事件，onload事件也完成.

Event: 'did-fail-load'

返回:

• eventEvent
• errorCodeInteger
• errorDescriptionString
• validatedURLString

这个事件类似 did-finish-load，但是是在加载失败或取消加载时发出, 例如， window.stop()请求结束.错误代码的完整列表和它们的含义都可以在 here找到.

Event: 'did-frame-finish-load'

返回:

• eventEvent
• isMainFrameBoolean

当一个 frame 导航完成的时候发出事件.

Event: 'did-start-loading'

当 tab 的spinner 开始 spinning的时候.

Event: 'did-stop-loading'

当 tab 的spinner 结束 spinning的时候.

Event: 'did-get-response-details'

返回:

• eventEvent
• statusBoolean
• newURLString
• originalURLString
• httpResponseCodeInteger
• requestMethodString
• referrerString
• headersObject

当有关请求资源的详细信息可用的时候发出事件. status标识了 socket链接来下载资源.

Event: 'did-get-redirect-request'

返回:

• eventEvent
• oldURLString
• newURLString
• isMainFrameBoolean
• httpResponseCodeInteger
• requestMethodString
• referrerString
• headersObject

当在请求资源时收到重定向的时候发出事件.

Event: 'dom-ready'

返回:

• eventEvent

当指定 frame 中的 文档加载完成的时候发出事件.

Event: 'page-favicon-updated'

返回:

• eventEvent
• faviconsArray - Array of URLs

当 page 收到图标 url 的时候发出事件.

Event: 'new-window'

返回:

• eventEvent
• urlString
• frameNameString
• dispositionString - 可为 default, foreground-tab, background-tab, new-window和 other.
• optionsObject - 创建新的 BrowserWindow时使用的参数.

当 page 请求打开指定 url 窗口的时候发出事件.这可以是通过 window.open或一个外部连接如 <a target='_blank'>发出的请求.

默认指定 url的 BrowserWindow会被创建.

调用 event.preventDefault()可以用来阻止打开窗口.

Event: 'will-navigate'

返回:

• eventEvent
• urlString

当用户或 page 想要开始导航的时候发出事件.它可在当 window.location对象改变或用户点击 page 中的链接的时候发生.

当使用 api(如 webContents.loadURL和 webContents.back) 以编程方式来启动导航的时候，这个事件将不会发出.

它也不会在页内跳转发生， 例如点击锚链接或更新 window.location.hash.使用 did-navigate-in-page事件可以达到目的.

调用 event.preventDefault()可以阻止导航.

Event: 'did-navigate'

返回:

• eventEvent
• urlString

当一个导航结束时候发出事件.

页内跳转时不会发出这个事件，例如点击锚链接或更新 window.location.hash.使用 did-navigate-in-page事件可以达到目的.

Event: 'did-navigate-in-page'

返回:

• eventEvent
• urlString

当页内导航发生的时候发出事件.

当页内导航发生的时候，page 的url 改变，但是不会跳出界面.例如当点击锚链接时或者 DOM 的 hashchange事件发生.

Event: 'crashed'

当渲染进程崩溃的时候发出事件.

Event: 'plugin-crashed'

返回:

• eventEvent
• nameString
• versionString

当插件进程崩溃时候发出事件.

Event: 'destroyed'

当 webContents被删除的时候发出事件.

Event: 'devtools-opened'

当开发者工具栏打开的时候发出事件.

Event: 'devtools-closed'

当开发者工具栏关闭时候发出事件.

Event: 'devtools-focused'

当开发者工具栏获得焦点或打开的时候发出事件.

Event: 'certificate-error'

返回:

• eventEvent
• urlURL
• errorString - The error code
• certificateObject
  • dataBuffer - PEM encoded data
  • issuerNameString
• callbackFunction

当验证证书或 url失败的时候发出事件.

使用方法类似 app的 certificate-error事件.

Event: 'select-client-certificate'

返回:

• eventEvent
• urlURL
• certificateList[Objects]
  • dataBuffer - PEM encoded data
  • issuerNameString - Issuer's Common Name
• callbackFunction

当请求客户端证书的时候发出事件.

使用方法类似 app的 select-client-certificate事件.

Event: 'login'

返回:

• eventEvent
• requestObject
  • methodString
  • urlURL
  • referrerURL
• authInfoObject
  • isProxyBoolean
  • schemeString
  • hostString
  • portInteger
  • realmString
• callbackFunction

当 webContents想做基本验证的时候发出事件.

使用方法类似 the loginevent of app.

Event: 'found-in-page'

返回:

• eventEvent
• resultObject
  • requestIdInteger
  • finalUpdateBoolean - 标识是否还有更多的值可以查看.
  • activeMatchOrdinalInteger (可选) - 活动匹配位置
  • matchesInteger (可选) - 匹配数量.
  • selectionAreaObject (可选) - 协调首个匹配位置.

当使用 webContents.findInPage进行页内查找并且找到可用值得时候发出事件.

Event: 'media-started-playing'

当媒体开始播放的时候发出事件.

Event: 'media-paused'

当媒体停止播放的时候发出事件.

Event: 'did-change-theme-color'

当page 的主题色时候发出事件.这通常由于引入了一个 meta 标签 :

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

Event: 'cursor-changed'

返回:

• eventEvent
• typeString
• imageNativeImage (可选)
• scaleFloat (可选)

当鼠标的类型发生改变的时候发出事件. 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, grabbing, custom.

如果 type参数值为 custom, image参数会在一个NativeImage中控制自定义鼠标图片, 并且 scale会控制图片的缩放比例.

实例方法

webContents对象有如下的实例方法:

webContents.loadURL(url[, options])

• urlURL
• optionsObject (可选)
  • httpReferrerString - A HTTP Referrer url.
  • userAgentString - 产生请求的用户代理
  • extraHeadersString - 以 "\n" 分隔的额外头

在窗口中加载 url, url必须包含协议前缀, 比如 http://或 file://. 如果加载想要忽略 http 缓存，可以使用 pragma头来达到目的.

const options = {"extraHeaders" : "pragma: no-cache\n"}
webContents.loadURL(url, options)

webContents.downloadURL(url)

• urlURL

初始化一个指定 url的资源下载，不导航跳转. session的 will-download事件会触发.

webContents.getURL()

返回当前page 的 url.

var win = new BrowserWindow({width: 800, height: 600});
win.loadURL("http://github.com");
var currentURL = win.webContents.getURL();

webContents.getTitle()

返回当前page 的 标题.

webContents.isLoading()

返回一个布尔值，标识当前页是否正在加载.

webContents.isWaitingForResponse()

返回一个布尔值，标识当前页是否正在等待主要资源的第一次响应.

webContents.stop()

停止还为开始的导航.

webContents.reload()

重载当前页.

webContents.reloadIgnoringCache()

重载当前页，忽略缓存.

webContents.canGoBack()

返回一个布尔值，标识浏览器是否能回到前一个page.

webContents.canGoForward()

返回一个布尔值，标识浏览器是否能前往下一个page.

webContents.canGoToOffset(offset)

• offsetInteger

返回一个布尔值，标识浏览器是否能前往指定 offset的page.

webContents.clearHistory()

清除导航历史.

webContents.goBack()

让浏览器回退到前一个page.

webContents.goForward()

让浏览器回前往下一个page.

webContents.goToIndex(index)

• indexInteger

让浏览器回前往指定 index的page.

webContents.goToOffset(offset)

• offsetInteger

导航到相对于当前页的偏移位置页.

webContents.isCrashed()

渲染进程是否崩溃.

webContents.setUserAgent(userAgent)

• userAgentString

重写本页用户代理.

webContents.getUserAgent()

返回一个 String，标识本页用户代理信息.

webContents.insertCSS(css)

• cssString

为当前页插入css.

webContents.executeJavaScript(code[, userGesture, callback])

• codeString
• userGestureBoolean (可选)
• callbackFunction (可选) - 脚本执行完成后调用的回调函数.
  • result

评估 page 代码.

浏览器窗口中的一些 HTML API ，例如 requestFullScreen，只能被用户手势请求.设置 userGesture为 true可以取消这个限制.

win.webContents.executeJavaScript('\
      $(".skey").focus();\
');

webContents.setAudioMuted(muted)

• mutedBoolean

减缓当前也的 audio 的播放速度.

webContents.isAudioMuted()

返回一个布尔值，标识当前页是否减缓了 audio 的播放速度.

webContents.undo()

执行网页的编辑命令 undo.

webContents.redo()

执行网页的编辑命令 redo.

webContents.cut()

执行网页的编辑命令 cut.

webContents.copy()

执行网页的编辑命令 copy.

webContents.paste()

执行网页的编辑命令 paste.

webContents.pasteAndMatchStyle()

执行网页的编辑命令 pasteAndMatchStyle.

webContents.delete()

执行网页的编辑命令 delete.

webContents.selectAll()

执行网页的编辑命令 selectAll.

webContents.unselect()

执行网页的编辑命令 unselect.

webContents.replace(text)

• textString

执行网页的编辑命令 replace.

webContents.replaceMisspelling(text)

• textString

执行网页的编辑命令 replaceMisspelling.

webContents.insertText(text)

• textString

插入 text到获得了焦点的元素.

webContents.findInPage(text[, options])

• textString - 查找内容, 不能为空.
• optionsObject (可选)
  • forwardBoolean - 是否向前或向后查找, 默认为 true.
  • findNextBoolean - 当前操作是否是第一次查找或下一次查找, 默认为 false.
  • matchCaseBoolean - 查找是否区分大小写, 默认为 false.
  • wordStartBoolean -是否仅以首字母查找. 默认为 false.
  • medialCapitalAsWordStartBoolean - 是否结合 wordStart,如果匹配是大写字母开头，后面接小写字母或无字母，那么就接受这个词中匹配.接受几个其它的合成词匹配, 默认为 false.

发起请求，在网页中查找所有与 text相匹配的项，并且返回一个 Integer来表示这个请求用的请求Id.这个请求结果可以通过订阅 found-in-page事件来取得.

webContents.stopFindInPage(action)

• actionString - 指定一个行为来接替停止 webContents.findInPage请求.
  • clearSelection- 转变为一个普通的 selection.
  • keepSelection- 清除 selection.
  • activateSelection- 获取焦点并点击 selection node.

使用给定的 action来为 webContents停止任何 findInPage请求.

webContents.on('found-in-page', function(event, result) {
  if (result.finalUpdate)
    webContents.stopFindInPage("clearSelection");
});
const requestId = webContents.findInPage("api");

webContents.hasServiceWorker(callback)

• callbackFunction

检查是否有任何 ServiceWorker 注册了，并且返回一个布尔值，来作为 callback响应的标识.

webContents.unregisterServiceWorker(callback)

• callbackFunction

如果存在任何 ServiceWorker ，则全部注销，并且当JS承诺执行行或JS拒绝执行而失败的时候，返回一个布尔值，它标识了相应的 callback.

webContents.print([options])

• optionsObject (可选)
  • silentBoolean - 不需要请求用户的打印设置. 默认为 false.
  • printBackgroundBoolean - 打印背景和网页图片. 默认为 false.

打印窗口的网页. 当设置 silent为 false的时候，Electron 将使用系统默认的打印机和打印方式来打印.

在网页中调用 window.print()和 调用 webContents.print({silent: false, printBackground: false})具有相同的作用.

注意: 在 Windows, 打印 API 依赖于 pdf.dll. 如果你的应用不使用任何的打印, 你可以安全删除 pdf.dll来减少二进制文件的size.

webContents.printToPDF(options, callback)

• optionsObject
  • marginsTypeInteger - 指定使用的 margin type. 默认 margin 使用 0, 无 margin 使用 1, 最小化 margin 使用 2.
  • pageSizeString - 指定生成的PDF文件的page size. 可以是 A3, A4, A5, Legal, Letter和 Tabloid.
  • printBackgroundBoolean - 是否打印 css 背景.
  • printSelectionOnlyBoolean - 是否只打印选中的部分.
  • landscapeBoolean - landscape 为 true, portrait 为 false.
• callbackFunction

打印窗口的网页为 pdf ，使用 Chromium 预览打印的自定义设置.

完成时使用 callback(error, data)调用 callback. data是一个 Buffer，包含了生成的 pdf 数据.

默认，空的 options被视为 :

{
  marginsType: 0,
  printBackground: false,
  printSelectionOnly: false,
  landscape: false
}

const BrowserWindow = require('electron').BrowserWindow;
const fs = require('fs');
var win = new BrowserWindow({width: 800, height: 600});
win.loadURL("https://www.w3cschool.cn");
win.webContents.on("did-finish-load", function() {
  // Use default printing options
  win.webContents.printToPDF({}, function(error, data) {
    if (error) throw error;
    fs.writeFile("/tmp/print.pdf", data, function(error) {
      if (error)
        throw error;
      console.log("Write PDF successfully.");
    })
  })
});

webContents.addWorkSpace(path)

• pathString

添加指定的路径给开发者工具栏的 workspace.必须在 DevTools 创建之后使用它 :

mainWindow.webContents.on('devtools-opened', function() {
  mainWindow.webContents.addWorkSpace(__dirname);
});

webContents.removeWorkSpace(path)

• pathString

从开发者工具栏的 workspace 删除指定的路径.

webContents.openDevTools([options])

• optionsObject (可选)
  • detachBoolean - 在一个新窗口打开开发者工具栏

打开开发者工具栏.

webContents.closeDevTools()

关闭开发者工具栏.

webContents.isDevToolsOpened()

返回布尔值，开发者工具栏是否打开.

webContents.isDevToolsFocused()

返回布尔值，开发者工具栏视图是否获得焦点.

webContents.toggleDevTools()

Toggles 开发者工具.

webContents.inspectElement(x, y)

• xInteger
• yInteger

在 (x, y) 开始检测元素.

webContents.inspectServiceWorker()

为 service worker 上下文打开开发者工具栏.

webContents.send(channel[, arg1][, arg2][, ...])

• channelString
• arg(可选)

通过 channel发送异步消息给渲染进程，你也可发送任意的参数.参数应该在 JSON 内部序列化，并且此后没有函数或原形链被包括了.

渲染进程可以通过使用 ipcRenderer监听 channel来处理消息.

例子，从主进程向渲染进程发送消息 :

// 主进程.
var window = null;
app.on('ready', function() {
  window = new BrowserWindow({width: 800, height: 600});
  window.loadURL('file://' + __dirname + '/index.html');
  window.webContents.on('did-finish-load', function() {
    window.webContents.send('ping', 'whoooooooh!');
  });
});

<!-- index.html -->
<html>
<body>
  <script>
    require('electron').ipcRenderer.on('ping', function(event, message) {
      console.log(message);  // Prints "whoooooooh!"
    });
  </script>
</body>
</html>

webContents.enableDeviceEmulation(parameters)

parametersObject, properties:

• screenPositionString - 指定需要模拟的屏幕 (默认 : desktop)
  • desktop
  • mobile
• screenSizeObject - 设置模拟屏幕 size (screenPosition == mobile)
  • widthInteger - 设置模拟屏幕 width
  • heightInteger - 设置模拟屏幕 height
• viewPositionObject - 在屏幕放置 view (screenPosition == mobile) (默认: {x: 0, y: 0})
  • xInteger - 设置偏移左上角的x轴
  • yInteger - 设置偏移左上角的y轴
• deviceScaleFactorInteger - 设置设备比例因子 (如果为0，默认为原始屏幕比例) (默认: 0)
• viewSizeObject - 设置模拟视图 size (空表示不覆盖)
  • widthInteger - 设置模拟视图 width
  • heightInteger - 设置模拟视图 height
• fitToViewBoolean - 如果有必要的话，是否把模拟视图按比例缩放来适应可用空间 (默认: false)
• offsetObject - 可用空间内的模拟视图偏移 (不在适应模式) (默认: {x: 0, y: 0})
  • xFloat - 设置相对左上角的x轴偏移值
  • yFloat - 设置相对左上角的y轴偏移值
• scaleFloat - 可用空间内的模拟视图偏移 (不在适应视图模式) (默认: 1)

使用给定的参数来开启设备模拟.

webContents.disableDeviceEmulation()

使用 webContents.enableDeviceEmulation关闭设备模拟.

webContents.sendInputEvent(event)

• eventObject
  • typeString (必需) - 事件类型，可以是 mouseDown, mouseUp, mouseEnter, mouseLeave, contextMenu, mouseWheel, mouseMove, keyDown, keyUp, char.
  • modifiersArray - 事件的 modifiers 数组, 可以是 include shift, control, alt, meta, isKeypad, isAutoRepeat, leftButtonDown, middleButtonDown, rightButtonDown, capsLock,numLock, left, right.

向 page 发送一个输入 event.

对键盘事件来说，event对象还有如下属性 :

• keyCodeString (必需) - 特点是将作为键盘事件发送. 可用的 key codes Accelerator.

对鼠标事件来说，event对象还有如下属性 :

• xInteger (required)
• yInteger (required)
• buttonString - button 按下, 可以是 left, middle, right
• globalXInteger
• globalYInteger
• movementXInteger
• movementYInteger
• clickCountInteger

对鼠标滚轮事件来说，event对象还有如下属性 :

• deltaXInteger
• deltaYInteger
• wheelTicksXInteger
• wheelTicksYInteger
• accelerationRatioXInteger
• accelerationRatioYInteger
• hasPreciseScrollingDeltasBoolean
• canScrollBoolean

webContents.beginFrameSubscription(callback)

• callbackFunction

开始订阅 提交 事件和捕获数据帧，当有 提交 事件时，使用 callback(frameBuffer)调用 callback.

frameBuffer是一个包含原始像素数据的 Buffer,像素数据是按照 32bit BGRA 格式有效存储的，但是实际情况是取决于处理器的字节顺序的(大多数的处理器是存放小端序的，如果是在大端序的处理器上，数据是 32bit ARGB 格式).

webContents.endFrameSubscription()

停止订阅帧提交事件.

webContents.savePage(fullPath, saveType, callback)

• fullPathString - 文件的完整路径.
• saveTypeString - 指定保存类型.
  • HTMLOnly- 只保存html.
  • HTMLComplete- 保存整个 page 内容.
  • MHTML- 保存完整的 html 为 MHTML.
• callbackFunction - function(error) {}.
  • errorError

如果保存界面过程初始化成功，返回 true.

win.loadURL('https://www.w3cschool.cn');
win.webContents.on('did-finish-load', function() {
  win.webContents.savePage('/tmp/test.html', 'HTMLComplete', function(error) {
    if (!error)
      console.log("Save page successfully");
  });
});

实例属性

WebContents对象也有下列属性:

webContents.session

返回这个 webContents使用的 session 对象.

webContents.hostWebContents

返回这个 webContents的父 webContents.

webContents.devToolsWebContents

获取这个 WebContents的开发者工具栏的 WebContents.

注意: 用户不可保存这个对象，因为当开发者工具栏关闭的时候它的值为 null.

webContents.debugger

调试 API 为 remote debugging protocol提供交替传送.

try {
  win.webContents.debugger.attach("1.1");
} catch(err) {
  console.log("Debugger attach failed : ", err);
};
win.webContents.debugger.on('detach', function(event, reason) {
  console.log("Debugger detached due to : ", reason);
});
win.webContents.debugger.on('message', function(event, method, params) {
  if (method == "Network.requestWillBeSent") {
    if (params.request.url == "https://www.w3cschool.cn")
      win.webContents.debugger.detach();
  }
})
win.webContents.debugger.sendCommand("Network.enable");

webContents.debugger.attach([protocolVersion])

• protocolVersionString (可选) - 请求调试协议版本.

添加 webContents调试.

webContents.debugger.isAttached()

返回一个布尔值，标识是否已经给 webContents添加了调试.

webContents.debugger.detach()

删除 webContents调试.

webContents.debugger.sendCommand(method[, commandParams, callback])

• methodString - 方法名, 应该是由远程调试协议定义的方法.
• commandParamsObject (可选) - 请求参数为 JSON 对象.
• callbackFunction (可选) - Response
  • errorObject - 错误消息，标识命令失败.
  • resultObject - 回复在远程调试协议中由 'returns'属性定义的命令描述.

发送给定命令给调试目标.

Event: 'detach'

• eventEvent
• reasonString - 拆分调试器原因.

在调试 session 结束时发出事件.这在 webContents关闭时或 webContents请求开发者工具栏时发生.

Event: 'message'

• eventEvent
• methodString - 方法名.
• paramsObject - 在远程调试协议中由 'parameters' 属性定义的事件参数.

每当调试目标发出事件时发出.