webFrame

自定义当前网页的呈现方式。

进程: 渲染器

🌐 Process: Renderer

info

如果你想从启用上下文隔离的渲染进程调用此 API， 请将 API 调用放在你的 preload 脚本中，并 使用 contextBridge API 暴露 它。

webFrame 导出的 Electron 模块是一个 WebFrame 类的实例，表示当前的框架。子框架可以通过某些属性和方法（例如 webFrame.firstChild）获取。

将当前页面缩放至 200% 的示例。

🌐 An example of zooming current page to 200%.

const { webFrame } = require('electron')

webFrame.setZoomFactor(2)

方法

🌐 Methods

WebFrame 类具有以下实例方法：

🌐 The WebFrame class has the following instance methods:

webFrame.setZoomFactor(factor)

• factor 双重 - 缩放因子；默认值为 1.0。

将缩放因子更改为指定的因子。缩放因子是缩放百分比除以100，因此300% = 3.0。

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

该系数必须大于 0.0。

🌐 The factor must be greater than 0.0.

webFrame.getZoomFactor()

返回 number - 当前的缩放因子。

🌐 Returns number - The current zoom factor.

webFrame.setZoomLevel(level)

• level 数字 - 缩放级别。

将缩放级别更改为指定级别。原始大小为 0，每增加或减少一级表示相比原始大小放大或缩小 20%，默认的最大和最小限制分别为原始大小的 300% 和 50%。

🌐 Changes the zoom level to the specified level. 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.

note

Chromium级别的缩放策略是同源策略，这意味着特定域的缩放等级会在所有具有相同域的窗口实例之间传播。区分窗口的URL将使缩放在每个窗口上单独生效。

webFrame.getZoomLevel()

返回 number - 当前的缩放级别。

🌐 Returns number - The current zoom level.

webFrame.setVisualZoomLevelLimits(minimumLevel, maximumLevel)

• minimumLevel 号码
• maximumLevel 号码

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

🌐 Sets the maximum and minimum pinch-to-zoom level.

note

在 Electron 中，视觉缩放默认是禁用的。要重新启用它，请调用：

webFrame.setVisualZoomLevelLimits(1, 3)

note

视觉缩放仅适用于捏合缩放手势。Cmd+/-/0 缩放快捷键由应用菜单中的 'zoomIn'、'zoomOut' 和 'resetZoom' MenuItem 角色控制。要禁用快捷键，请手动定义菜单并在定义中省略缩放角色。

webFrame.setSpellCheckProvider(language, provider)

• language 字符串
• provider 对象
  • spellCheck 函数
    • words 字符串数组
    • callback 函数
      • misspeltWords 字符串数组

设置用于输入字段和文本区域中的拼写检查的提供程序。

🌐 Sets a provider for spell checking in input fields and text areas.

如果你想使用这种方法，在构建窗口时必须禁用内置拼写检查器。

🌐 If you want to use this method you must disable the builtin spellchecker when you construct the window.

const mainWindow = new BrowserWindow({
  webPreferences: {
    spellcheck: false
  }
})

provider 必须是一个拥有 spellCheck 方法的对象，该方法接受一个用于拼写检查的单词数组。spellCheck 函数异步运行，并在完成后调用 callback 函数，传递一个拼写错误单词的数组。

🌐 The provider must be an object that has a spellCheck method that accepts an array of individual words for spellchecking. The spellCheck function runs asynchronously and calls the callback function with an array of misspelt words when complete.

使用 节点拼写检查器 作为提供者的示例：

🌐 An example of using node-spellchecker as provider:

const { webFrame } = require('electron')

const spellChecker = require('spellchecker')

webFrame.setSpellCheckProvider('en-US', {
  spellCheck (words, callback) {
    setTimeout(() => {
      const misspelled = words.filter(x => spellchecker.isMisspelled(x))
      callback(misspelled)
    }, 0)
  }
})

webFrame.insertCSS(css[, options])

• css 字符串
• options 对象（可选）
  • cssOrigin 字符串（可选） - 可以是 'user' 或 'author'。设置插入样式表的级联来源。默认值为 'author'。

返回 string - 一个用于插入的 CSS 的键，之后可以通过 webFrame.removeInsertedCSS(key) 来删除该 CSS。

🌐 Returns string - A key for the inserted CSS that can later be used to remove the CSS via webFrame.removeInsertedCSS(key).

将 CSS 注入当前网页，并返回插入样式表的唯一键。

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

webFrame.removeInsertedCSS(key)

• key 字符串

从当前网页中移除已插入的 CSS。样式表通过其键来识别，该键由 webFrame.insertCSS(css) 返回。

🌐 Removes the inserted CSS from the current web page. The stylesheet is identified by its key, which is returned from webFrame.insertCSS(css).

webFrame.insertText(text)

• text 字符串

将 text 插入到当前焦点元素。

🌐 Inserts text to the focused element.

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

• code 字符串
• userGesture 布尔值（可选）- 默认值为 false。
• callback 函数（可选）- 脚本执行后调用。除非帧被挂起（例如显示模态警告），否则执行将是同步的，回调将在方法返回之前被调用。为了与该方法的旧版本兼容，错误参数为第二个。
  • result 任何
  • error 错误

返回 Promise<any> —— 一个 Promise，如果代码执行成功则解析为执行结果，如果执行抛出异常或返回被拒绝的 Promise，则被拒绝。

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

在页面中评估 code。

🌐 Evaluates code in page.

在浏览器窗口中，一些 HTML API（如 requestFullScreen）只能通过用户的手势来调用。将 userGesture 设置为 true 将移除此限制。

🌐 In the browser window some HTML APIs like requestFullScreen can only be invoked by a gesture from the user. Setting userGesture to true will remove this limitation.

webFrame.executeJavaScriptInIsolatedWorld(worldId, scripts[, userGesture][, callback])

• worldId 整数 - 运行 JavaScript 的世界 ID，0 是默认的主世界（运行内容的地方），999 是 Electron 的 contextIsolation 功能使用的世界。接受的值范围为 1..536870911。
• scripts 网页来源[]
• userGesture 布尔值（可选）- 默认值为 false。
• callback 函数（可选）- 在脚本执行后调用。除非帧被挂起（例如显示模态警告），否则执行将是同步的，并且回调将在方法返回之前被调用。为了兼容该方法的旧版本，错误参数为第二个。
  • result 任何
  • error 错误

返回 Promise<any> - 一个 Promise，如果代码执行成功则解析为执行结果，如果执行无法启动则被拒绝。

🌐 Returns Promise<any> - A promise that resolves with the result of the executed code or is rejected if execution could not start.

类似于 executeJavaScript，但在独立的环境中评估 scripts。

🌐 Works like executeJavaScript but evaluates scripts in an isolated context.

请注意，当脚本执行失败时，返回的 Promise 不会被拒绝，并且 result 将会是 undefined。这是因为 Chromium 不会将隔离世界的错误传递到外部世界。

🌐 Note that when the execution of script fails, the returned promise will not reject and the result would be undefined. This is because Chromium does not dispatch errors of isolated worlds to foreign worlds.

webFrame.setIsolatedWorldInfo(worldId, info)

• worldId 整数 - 运行 JavaScript 的世界的 ID，0 是默认的世界，999 是 Electron contextIsolation 功能使用的世界。Chrome 扩展保留了 [1 << 20, 1 << 29) 范围内的 ID。这里可以提供任意整数。
• info 对象
  • securityOrigin 字符串（可选）- 隔离环境的安全来源。
  • csp 字符串（可选）- 用于隔离环境的内容安全策略。
  • name 字符串（可选）- 用于隔离世界的名称。在开发者工具中非常有用。

设置隔离世界的安全源、内容安全策略和名称。

🌐 Set the security origin, content security policy and name of the isolated world.

note

如果指定了 csp，那么 securityOrigin 也必须指定。

webFrame.getResourceUsage()

返回 Object：

🌐 Returns Object:

• images 内存使用详情
• scripts 内存使用详情
• cssStyleSheets 内存使用详情
• xslStyleSheets 内存使用详情
• fonts 内存使用详情
• other 内存使用详情

返回一个描述 Blink 内部内存缓存使用信息的对象。

🌐 Returns an object describing usage information of Blink's internal memory caches.

const { webFrame } = require('electron')

console.log(webFrame.getResourceUsage())

这将生成：

🌐 This will generate:

{
  images: {
    count: 22,
    size: 2549,
    liveSize: 2542
  },
  cssStyleSheets: { /* same with "images" */ },
  xslStyleSheets: { /* same with "images" */ },
  fonts: { /* same with "images" */ },
  other: { /* same with "images" */ }
}

webFrame.clearCache()

尝试释放不再使用的内存（例如来自之前导航的图片）。

🌐 Attempts to free memory that is no longer being used (like images from a previous navigation).

请注意，盲目调用此方法可能会让 Electron 变慢，因为它必须重新填充这些已清空的缓存，你应该仅在应用中的某个事件发生后认为你的页面实际上正在使用较少内存时才调用它（例如，你已经从一个非常重的页面导航到一个几乎为空的页面，并打算停留在那里）。

🌐 Note that blindly calling this method probably makes Electron slower since it will have to refill these emptied caches, you should only call it if an event in your app has occurred that makes you think your page is actually using less memory (i.e. you have navigated from a super heavy page to a mostly empty one, and intend to stay there).

webFrame.getFrameForSelector(selector)

• selector 字符串 - 一个框架元素的 CSS 选择器。

返回 WebFrame | null - 在 webFrame's 文档中由 selector 选择的框架元素，如果 selector 未选择框架或框架不在当前渲染进程中，则返回 null。

🌐 Returns WebFrame | null - The frame element in webFrame's document selected by selector, null would be returned if selector does not select a frame or if the frame is not in the current renderer process.

webFrame.findFrameByName(name)

• name 字符串

返回 WebFrame | null - 如果存在具有提供的 name、null 的 webFrame 子项，则返回它；如果没有这样的框架，或者该框架不在当前的渲染器进程中，则返回该值。

🌐 Returns WebFrame | null - A child of webFrame with the supplied name, null would be returned if there's no such frame or if the frame is not in the current renderer process.

webFrame.findFrameByRoutingId(routingId) 已弃用

🌐 webFrame.findFrameByRoutingId(routingId) Deprecated

• routingId 整数 - 一个 Integer，表示当前渲染器进程中的唯一帧 ID。路由 ID 可以从 WebFrame 实例（webFrame.routingId）中获取，也会通过特定帧的 WebContents 导航事件（例如 did-frame-navigate）传递

返回 WebFrame | null - 如果未找到，则包含提供的 routingId、null。

🌐 Returns WebFrame | null - that has the supplied routingId, null if not found.

**已弃用：**请使用新的 webFrame.findFrameByToken API。

webFrame.findFrameByToken(frameToken)

• frameToken 字符串 - 一个 string，表示当前渲染器进程中的唯一帧 ID。帧令牌可以从 WebFrame 实例（webFrame.frameToken）中获取，也可以使用 webFrameMain.frameToken 从 WebFrameMain 实例中获取。

返回 WebFrame | null - 如果未找到，则包含提供的 frameToken、null。

🌐 Returns WebFrame | null - that has the supplied frameToken, null if not found.

webFrame.isWordMisspelled(word)

• word 字符串 - 需要进行拼写检查的单词。

返回 boolean - 如果根据内置拼写检查器单词拼写错误，则返回 true，否则返回 false。如果未加载任何字典，则始终返回 false。

🌐 Returns boolean - True if the word is misspelled according to the built in spellchecker, false otherwise. If no dictionary is loaded, always return false.

webFrame.getWordSuggestions(word)

• word 字符串 - 拼写错误的单词。

返回 string[] - 给定单词的建议词列表。如果单词拼写正确，结果将为空。

🌐 Returns string[] - A list of suggested words for a given word. If the word is spelled correctly, the result will be empty.

属性

🌐 Properties

webFrame.top 只读

🌐 webFrame.top Readonly

一个 WebFrame | null，表示 webFrame 所属的框架层次结构中的顶层框架，如果顶层框架不在当前渲染进程中，该属性将是 null。

🌐 A WebFrame | null representing top frame in frame hierarchy to which webFrame belongs, the property would be null if top frame is not in the current renderer process.

webFrame.opener 只读

🌐 webFrame.opener Readonly

WebFrame | null 表示打开了 webFrame 的框架，如果没有打开者或者打开者不在当前渲染进程中，该属性将是 null。

🌐 A WebFrame | null representing the frame which opened webFrame, the property would be null if there's no opener or opener is not in the current renderer process.

webFrame.parent 只读

🌐 webFrame.parent Readonly

一个表示 webFrame 父帧的 WebFrame | null，如果 webFrame 是顶层或父帧不在当前渲染进程中，则该属性为 null。

🌐 A WebFrame | null representing parent frame of webFrame, the property would be null if webFrame is top or parent is not in the current renderer process.

webFrame.firstChild 只读

🌐 webFrame.firstChild Readonly

WebFrame | null 表示 webFrame 的第一个子框架，如果 webFrame 没有子节点，或者第一个子节点不在当前渲染进程中，该属性将是 null。

🌐 A WebFrame | null representing the first child frame of webFrame, the property would be null if webFrame has no children or if first child is not in the current renderer process.

webFrame.nextSibling 只读

🌐 webFrame.nextSibling Readonly

WebFrame | null 表示下一个兄弟框架，如果 webFrame 是其父框架中的最后一个框架，或者下一个兄弟框架不在当前渲染器进程中，则该属性将是 null。

🌐 A WebFrame | null representing next sibling frame, the property would be null if webFrame is the last frame in its parent or if the next sibling is not in the current renderer process.

webFrame.routingId 只读 已弃用

🌐 webFrame.routingId Readonly Deprecated

Integer 表示当前渲染器进程中唯一的帧 ID。引用相同底层帧的不同 WebFrame 实例将具有相同的 routingId。

🌐 An Integer representing the unique frame id in the current renderer process. Distinct WebFrame instances that refer to the same underlying frame will have the same routingId.

**已弃用：**请使用新的 webFrame.frameToken API。

webFrame.frameToken 只读

🌐 webFrame.frameToken Readonly

string 表示当前渲染器进程中唯一的帧标记。指向相同底层帧的不同 WebFrame 实例将具有相同的 frameToken。

🌐 A string representing the unique frame token in the current renderer process. Distinct WebFrame instances that refer to the same underlying frame will have the same frameToken.