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 为 fal...	支持
page-favicon-updated	在页面收到 favicon URL 时触发。	支持
content-bounds-updated	在页面调用 window.moveTo、window.resizeTo 等相关 API 时触发。	支持
did-create-window	在页面通过 window.open() 创建新 BrowserWindow 后触发。	支持
will-navigate	在主 frame 即将导航时触发，该事件中 isInPlace 属性始终为 false；若 fram...	支持
will-frame-navigate	在任意 frame 即将导航时触发，该事件中 isInPlace 属性始终为 false；若 fra...	支持
did-start-navigation	在导航开始时触发，同文档导航包括锚点跳转、pushState/replaceState 及同页历史导...	支持
will-redirect	在导航过程中发生服务端重定向时触发，同文档导航包括锚点跳转、pushState/replaceSta...	支持
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.preventDefaul...	支持
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 需要选择蓝牙设备时触发，...	支持
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 已导航或已销毁，则相关属性可能为 n...	支持

Methods（方法）

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