webContents API 列表

本模块包含 189 个 API。

Events（事件）

API	说明	鸿蒙支持
did-finish-load	在导航完成时触发，即标签页加载指示器停止转动且 onload 事件已派发。	支持
did-fail-load	类似 did-finish-load，但在加载失败时触发，完整错误码列表请参阅相关文档。	支持
did-fail-provisional-load	类似 did-fail-load，但在加载被取消时触发（例如调用了 window.stop()）。	支持
did-frame-finish-load	在某个 frame 完成导航时触发。	支持
did-start-loading	在标签页加载指示器开始转动时触发。	支持
did-stop-loading	在标签页加载指示器停止转动时触发。	支持
dom-ready	在顶层 frame 的文档加载完成时触发。	支持
page-title-updated	在导航过程中页面标题被设置时触发；若标题由文件 URL 合成，则 explicitSet 为 false。	支持
page-favicon-updated	在页面收到 favicon URL 时触发。	支持
content-bounds-updated	在页面调用 window.moveTo、window.resizeTo 等相关 API 时触发。	支持
did-create-window	在页面通过 window.open() 创建新 BrowserWindow 后触发。	支持
will-navigate	在主 frame 即将导航时触发，该事件中 isInPlace 属性始终为 false；若 frame 已完成导航或已销毁，则 frame 可能为 null。	支持
will-frame-navigate	在任意 frame 即将导航时触发，该事件中 isInPlace 属性始终为 false；若 frame 已完成导航或已销毁，则 frame 可能为 null。	支持
did-start-navigation	在导航开始时触发，同文档导航包括锚点跳转、pushState/replaceState 及同页历史导航。	支持
will-redirect	在导航过程中发生服务端重定向时触发，同文档导航包括锚点跳转、pushState/replaceState 及同页历史导航。	支持
did-redirect-navigation	在导航重定向完成后触发，同文档导航包括锚点跳转、pushState/replaceState 及同页历史导航。	支持
did-navigate	在主 frame 导航完成时触发。	支持
did-frame-navigate	在任意 frame 导航完成时触发。	支持
did-navigate-in-page	在任意 frame 发生页内导航时触发。	支持
will-prevent-unload	在 beforeunload 事件处理器尝试阻止页面卸载时触发。	支持
render-process-gone	在渲染进程意外消失时触发，通常是由于崩溃或被终止。	支持
unresponsive	在网页变得无响应时触发。	支持
responsive	在无响应的网页恢复响应时触发。	支持
plugin-crashed	在插件进程崩溃时触发。	支持
destroyed	在 webContents 被销毁时触发。	支持
input-event	在输入事件发送到 WebContents 时触发，详见 InputEvent。	支持
before-input-event	在页面派发 keydown 和 keyup 事件前触发，调用 event.preventDefault() 可阻止页面键盘事件及菜单快捷键。	支持
enter-html-full-screen	在窗口通过 HTML API 进入全屏状态时触发。	支持
leave-html-full-screen	在窗口通过 HTML API 退出全屏状态时触发。	支持
zoom-changed	在用户使用鼠标滚轮请求更改缩放级别时触发。	支持
blur	在 WebContents 失去焦点时触发。	支持
focus	在 WebContents 获得焦点时触发。	支持
devtools-open-url	在 DevTools 中点击链接或从上下文菜单选择「在新标签页中打开」时触发。	支持
devtools-search-query	在 DevTools 上下文菜单中对文本选择「搜索」时触发。	支持
devtools-opened	在 DevTools 打开时触发。	支持
devtools-closed	在 DevTools 关闭时触发。	支持
devtools-focused	在 DevTools 获得焦点或被打开时触发。	支持
certificate-error	在验证指定 URL 的证书失败时触发。	支持
select-client-certificate	在请求客户端证书时触发。	支持
login	在 webContents 需要进行基本身份验证时触发。	支持
found-in-page	在 webContents.findInPage 请求有结果时触发。	支持
media-started-playing	在媒体开始播放时触发。	支持
media-paused	在媒体暂停或播放结束时触发。	支持
audio-state-changed	在媒体变为有声或静音状态时触发。	支持
did-change-theme-color	在页面主题色发生变化时触发，通常由 meta 标签引起。	支持
update-target-url	在鼠标悬停于链接上或键盘焦点移至链接时触发。	支持
cursor-changed	在鼠标指针类型改变时触发，type 参数可为 pointer、crosshair、hand、text 等多种类型。	支持
context-menu	在需要显示上下文菜单时触发；若 frame 已导航或销毁，则相关属性可能为 null。	支持
select-bluetooth-device	在调用 navigator.bluetooth.requestDevice 需要选择蓝牙设备时触发，应通过 callback 传入所选设备的 deviceId。	支持
paint	在生成新帧时触发，buffer 中仅包含脏区域的数据。	支持
devtools-reload-page	在 DevTools 窗口指示 webContents 重新加载时触发。	支持
will-attach-webview	在 即将附加前触发，可修改 options 对象来调整客户页面的首选项。	支持
did-attach-webview	在 附加到当前页面时触发。	支持
console-message	在关联窗口输出控制台日志时触发。	支持
preload-error	在预加载脚本 preloadPath 抛出未处理异常时触发。	支持
ipc-message	在渲染进程通过 ipcRenderer.send() 发送异步消息时触发。	支持
ipc-message-sync	在渲染进程通过 ipcRenderer.sendSync() 发送同步消息时触发。	支持
preferred-size-changed	在页面首选大小发生变化时触发，该大小是无需滚动即可容纳文档布局的最小尺寸。	支持
frame-created	在主 frame 创建新子 frame 时触发；若 frame 已导航或已销毁，则相关属性可能为 null。	支持

Methods（方法）

API	说明	鸿蒙支持
webContents.getAllWebContents()	返回 WebContents[]，包含所有 WebContents 实例的数组。	支持
webContents.getFocusedWebContents()	返回 WebContents	null，即当前应用中获得焦点的 WebContents，否则返回 null。
webContents.fromId(id)	返回 WebContents	undefined，即具有指定 ID 的 WebContents 实例，不存在则返回 undefined。
webContents.fromFrame(frame)	返回 WebContents	undefined，即与指定 WebFrameMain 对应的 WebContents 实例，不存在则返回 undefined。
webContents.fromDevToolsTargetId(targetId)	返回 WebContents	undefined，即具有指定 TargetID 的 WebContents 实例，不存在则返回 undefined。
contents.loadURL(url[, options])	返回 Promise，页面加载完成后 resolve。	支持
contents.loadFile(filePath[, options])	返回 Promise，页面加载完成后 resolve。	支持
contents.downloadURL(url[, options])	在不导航的情况下发起对指定 URL 资源的下载，会触发 session 的 will-download 事件。	支持
contents.getURL()	返回 string，即当前网页的 URL。	支持
contents.getTitle()	返回 string，即当前网页的标题。	支持
contents.isDestroyed()	返回 boolean，表示网页是否已被销毁。	支持
contents.close([opts])	关闭页面，若页面阻止了 unload 事件，则 WebContents 不会被关闭。	支持
contents.focus()	聚焦网页。	支持
contents.isFocused()	返回 boolean，表示网页是否已获得焦点。	支持
contents.isLoading()	返回 boolean，表示网页是否仍在加载资源。	支持
contents.isLoadingMainFrame()	返回 boolean，表示主 frame（而非其中的 iframe）是否仍在加载。	支持
contents.isWaitingForResponse()	返回 boolean，表示网页是否正在等待主资源的首次响应。	支持
contents.stop()	停止所有待处理的导航。	支持
contents.reload()	重新加载当前网页。	支持
contents.reloadIgnoringCache()	忽略缓存并重新加载当前网页。	支持
contents.canGoBack()	返回 boolean，表示浏览器是否可以后退到上一页。	不支持
contents.canGoForward()	返回 boolean，表示浏览器是否可以前进到下一页。	不支持
contents.canGoToOffset(offset)	返回 boolean，表示网页是否可以导航到指定偏移位置。	不支持
contents.clearHistory()	清除导航历史记录。	不支持
contents.goBack()	使浏览器后退到上一页。	不支持
contents.goForward()	使浏览器前进到下一页。	不支持
contents.goToIndex(index)	使浏览器导航到指定的绝对历史索引位置。	不支持
contents.goToOffset(offset)	使浏览器导航到相对当前位置的指定偏移位置。	不支持
contents.isCrashed()	返回 boolean，表示渲染进程是否已崩溃。	支持
contents.forcefullyCrashRenderer()	强制终止当前托管此 webContents 的渲染进程，将触发 reason 为 killed 或 crashed 的 render-process-gone 事件。	支持
contents.setUserAgent(userAgent)	覆盖当前网页的 User-Agent。	支持
contents.getUserAgent()	返回 string，即当前网页的 User-Agent。	支持
contents.insertCSS(css[, options])	返回 Promise，resolve 后得到一个 key，可通过 contents.removeInsertedCSS(key) 移除已注入的 CSS。	支持
contents.removeInsertedCSS(key)	返回 Promise，移除成功后 resolve。	支持
contents.executeJavaScript(code[, userGesture])	返回 Promise，resolve 后得到所执行代码的结果。	支持
contents.executeJavaScriptInIsolatedWorld(worldId, scripts[, userGesture])	返回 Promise，在隔离的 world 中执行代码，resolve 后得到执行结果。	支持
contents.setIgnoreMenuShortcuts(ignore)	在此 WebContents 获得焦点时忽略应用菜单快捷键。	支持
contents.setWindowOpenHandler(handler)	设置新窗口打开处理器；返回 { action: 'deny' } 可取消新窗口的创建，返回 allow 则允许并可向新窗口传递参数。	支持
contents.setAudioMuted(muted)	静音或取消静音当前网页的音频。	支持
contents.isAudioMuted()	返回 boolean，表示当前页面是否已静音。	支持
contents.isCurrentlyAudible()	返回 boolean，表示当前是否有音频正在播放。	支持
contents.setZoomFactor(factor)	将缩放比例设置为指定值，缩放比例等于缩放百分比除以 100，例如 300% 对应 3.0。	支持
contents.getZoomFactor()	返回 number，即当前的缩放比例。	支持
contents.setZoomLevel(level)	设置缩放级别，原始大小为 0，每增减 1 级对应放大或缩小 20%，默认上下限分别为原始大小的 300% 和 50%。	支持
contents.getZoomLevel()	返回 number，即当前的缩放级别。	支持
contents.setVisualZoomLevelLimits(minimumLevel, maximumLevel)	返回 Promise，设置视觉缩放级别的最大值和最小值。	支持
contents.undo()	在网页中执行撤销编辑命令。	支持
contents.redo()	在网页中执行重做编辑命令。	支持
contents.cut()	在网页中执行剪切编辑命令。	支持
contents.copy()	在网页中执行复制编辑命令。	支持
contents.centerSelection()	将网页中当前选中的文本居中显示。	支持
contents.copyImageAt(x, y)	将指定位置的图像复制到剪贴板。	支持
contents.paste()	在网页中执行粘贴编辑命令。	支持
contents.pasteAndMatchStyle()	在网页中执行 pasteAndMatchStyle 编辑命令。	支持
contents.delete()	在网页中执行删除编辑命令。	支持
contents.selectAll()	在网页中执行全选编辑命令。	支持
contents.unselect()	在网页中执行取消选择编辑命令。	支持
contents.scrollToTop()	将当前 webContents 滚动到顶部。	支持
contents.scrollToBottom()	将当前 webContents 滚动到底部。	支持
contents.adjustSelection(options)	按指定偏移量调整当前焦点 frame 中文本选区的起始和结束位置，负值向文档开头移动，正值向文档末尾移动。	支持
contents.replace(text)	在网页中执行替换编辑命令。	支持
contents.replaceMisspelling(text)	在网页中执行纠正拼写错误的编辑命令。	支持
contents.insertText(text)	返回 Promise，向焦点元素插入文本。	支持
contents.findInPage(text[, options])	返回 Integer，即本次请求的 ID，默认 matchCase 为 false。	支持
contents.stopFindInPage(action)	停止 webContents.findInPage 请求并执行指定的后续操作。	支持
contents.capturePage([rect, opts])	返回 Promise，截取页面指定区域（或整页）的截图。	支持
contents.isBeingCaptured()	返回 boolean，表示当前页面是否正在被捕获，捕获器计数大于 0 时返回 true。	支持
contents.getPrintersAsync()	返回 Promise<PrinterInfo[]>，获取系统打印机列表。	支持
contents.print([options], [callback])	打印网页，默认不显示打印预览对话框。	支持
contents.printToPDF(options)	返回 Promise，将页面打印为 PDF，支持 A4、Letter 等多种纸张格式，默认为 Letter。	支持
contents.addWorkSpace(path)	将指定路径添加到 DevTools 工作区，须在 DevTools 创建后调用。	支持
contents.removeWorkSpace(path)	从 DevTools 工作区移除指定路径。	支持
contents.setDevToolsWebContents(devToolsWebContents)	将 devToolsWebContents 作为展示 DevTools 的目标 WebContents。	支持
contents.openDevTools([options])	打开 DevTools，停靠位置可为 left、right、bottom、undocked 或 detach，默认使用上次的停靠状态。	支持
contents.closeDevTools()	关闭 DevTools。	支持
contents.isDevToolsOpened()	返回 boolean，表示 DevTools 是否已打开。	支持
contents.isDevToolsFocused()	返回 boolean，表示 DevTools 视图是否已获得焦点。	支持
contents.getDevToolsTitle()	返回 string，即 DevTools 窗口的当前标题，仅在非停靠或分离模式下可见。	支持
contents.setDevToolsTitle(title)	将 DevTools 窗口的标题修改为 title，仅在非停靠或分离模式下生效。	支持
contents.toggleDevTools()	切换开发者工具的显示/隐藏状态。	支持
contents.inspectElement(x, y)	开始审查位于 (x, y) 位置的元素。	支持
contents.inspectSharedWorker()	为 shared worker 上下文打开开发者工具。	支持
contents.inspectSharedWorkerById(workerId)	根据 ID 检查对应的 shared worker。	支持
contents.getAllSharedWorkers()	返回 SharedWorkerInfo[] — 所有 Shared Worker 的信息。	支持
contents.inspectServiceWorker()	为 service worker 上下文打开开发者工具。	支持
contents.send(channel, ...args)	通过 channel 向渲染进程发送异步消息，参数使用结构化克隆算法序列化，原型链不会被包含在内。	支持
contents.sendToFrame(frameId, channel, ...args)	若目标 frame 与主 frame 属于不同进程，frameId 可为 [processId, frameId] 对。	支持
contents.postMessage(channel, message, [transfer])	向渲染进程发送消息，可选择性地转移零个或多个 MessagePortMain 对象的所有权。	支持
contents.enableDeviceEmulation(parameters)	启用设备模拟，支持配置屏幕位置（默认 desktop）、偏移量（默认 {x:0, y:0}）及缩放比例（默认 0）等参数。	支持
contents.disableDeviceEmulation()	禁用由 webContents.enableDeviceEmulation 启用的设备模拟。	支持
contents.sendInputEvent(inputEvent)	向页面发送输入事件。	支持
contents.beginFrameSubscription([onlyDirty ,]callback)	开始订阅页面渲染事件和捕获帧，每次发生渲染事件时以 callback(image, dirtyRect) 回调。	支持
contents.endFrameSubscription()	停止订阅帧渲染事件。	支持
contents.startDrag(item)	在 macOS 上设置拖拽项，icon 不能为空。	支持
contents.savePage(fullPath, saveType)	返回 Promise，页面保存成功时 resolve。	支持
contents.showDefinitionForSelection()	显示弹出词典，搜索页面中选中的单词。	不支持
contents.isOffscreen()	返回 boolean，表示是否启用了离屏渲染。	支持
contents.startPainting()	若离屏渲染已启用且当前未绘制，则开始绘制。	支持
contents.stopPainting()	若离屏渲染已启用且当前正在绘制，则停止绘制。	支持
contents.isPainting()	返回 boolean，若启用了离屏渲染，返回当前是否正在绘制。	支持
contents.setFrameRate(fps)	若启用了离屏渲染，将帧率设置为指定值，仅接受 1 到 240 之间的整数。	支持
contents.getFrameRate()	返回 Integer，若启用了离屏渲染，返回当前帧率。	支持
contents.invalidate()	安排 webContents 所在窗口进行整体重绘。	支持
contents.getWebRTCIPHandlingPolicy()	返回 string — WebRTC IP 处理策略。	支持
contents.setWebRTCIPHandlingPolicy(policy)	设置 WebRTC IP 处理策略；使用默认策略时，WebRTC 可枚举所有网络接口并绑定以发现公网地址。	支持
contents.getWebRTCUDPPortRange()	返回包含 WebRTC UDP 端口范围的对象。	支持
contents.setWebRTCUDPPortRange(udpPortRange)	设置 WebRTC 使用的 UDP 端口范围，默认不限制端口范围。	支持
contents.getMediaSourceId(requestWebContents)	返回 string — WebContents 流的标识符，可用于媒体捕获等场景。	支持
contents.getOSProcessId()	返回 Integer — 关联渲染进程的操作系统进程 ID。	支持
contents.getProcessId()	返回 Integer — 关联渲染进程的 Chromium 内部进程 ID。	支持
contents.takeHeapSnapshot(filePath)	返回 Promise，表示堆快照是否创建成功。	支持
contents.getBackgroundThrottling()	返回 boolean，表示该 WebContents 是否会在后台限制动画和定时器。	支持
contents.setBackgroundThrottling(allowed)	设置该 WebContents 在后台时是否限制动画和定时器。	支持
contents.getType()	返回 string — webContents 的类型，可为 backgroundPage、window、browserView、remote、webview 或 offscreen。	支持
contents.setImageAnimationPolicy(policy)	设置该 webContents 的图片动画策略，仅对新加载的图片生效，当前正在播放的图片不受影响。	支持

Properties（属性）

API	说明	鸿蒙支持
contents.ipc	仅限于该 WebContents 发送的 IPC 消息的 IpcMain 作用域实例。	支持
contents.audioMuted	布尔属性，控制该页面是否静音。	支持
contents.userAgent	字符串属性，设置该网页的 User-Agent。	支持
contents.zoomLevel	数值属性，设置该 webContents 的缩放级别。	支持
contents.zoomFactor	数值属性，设置该 webContents 的缩放因子。	支持
contents.frameRate	整数属性，设置 webContents 的帧率，仅接受 1 到 240 之间的值。	支持
contents.id	整数，表示该 WebContents 的唯一 ID，在整个 Electron 应用的所有 WebContents 实例中唯一。	支持
contents.session	该 webContents 使用的 Session 实例。	支持
contents.navigationHistory	该 webContents 使用的 NavigationHistory 实例。	支持
contents.hostWebContents	可能拥有该 WebContents 的父级 WebContents 实例。	支持
contents.devToolsWebContents	表示与该 WebContents 关联的 DevTools WebContents 的属性，值为 WebContents 或 null。	支持
contents.debugger	该 webContents 的 Debugger 实例。	支持
contents.backgroundThrottling	控制该 WebContents 在后台时是否限制动画和定时器的布尔属性。	支持
contents.mainFrame	WebFrameMain 属性，表示页面帧层级结构中的顶层 frame。	支持
contents.opener	WebFrameMain 属性，表示打开该 WebContents 的 frame（通过 open() 或带 target 属性的链接导航）。	支持