Skip to main content

webFrame

自定义当前网页的渲染。

¥Customize the rendering of the current web page.

进程：渲染器

¥Process: Renderer

[!重要] 如果你想从启用了上下文隔离的渲染进程调用此 API，请将 API 调用放在预加载脚本中，并使用 contextBridge API 对其进行 expose 操作。

¥[!IMPORTANT] If you want to call this API from a renderer process with context isolation enabled, place the API call in your preload script and expose it using the contextBridge API.

Electron 模块的 webFrame 导出是代表当前帧的 WebFrame 类的实例。子帧可以通过某些属性和方法检索（例如 webFrame.firstChild）。

¥webFrame export of the Electron module is an instance of the WebFrame class representing the current frame. Sub-frames can be retrieved by certain properties and methods (e.g. 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。

    ¥factor Double - Zoom factor; default is 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 数字 - 缩放级别。

    ¥level number - Zoom 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 将使缩放针对每个窗口起作用。

¥[!NOTE] The zoom policy at the Chromium level is same-origin, meaning that the zoom level for a specific domain propagates across all instances of windows with the same domain. Differentiating the window URLs will make zoom work per-window.

webFrame.getZoomLevel()​

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

¥Returns number - The current zoom level.

webFrame.setVisualZoomLevelLimits(minimumLevel, maximumLevel)​

  • minimumLevel 数字

    ¥minimumLevel number

  • maximumLevel 数字

    ¥maximumLevel number

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

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

[!NOTE] Electron 默认禁用视觉缩放。要重新启用它，请调用：

¥[!NOTE] Visual zoom is disabled by default in Electron. To re-enable it, call:

webFrame.setVisualZoomLevelLimits(1, 3)

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

¥[!NOTE] Visual zoom only applies to pinch-to-zoom behavior. Cmd+/-/0 zoom shortcuts are controlled by the 'zoomIn', 'zoomOut', and 'resetZoom' MenuItem roles in the application Menu. To disable shortcuts, manually define the Menu and omit zoom roles from the definition.

webFrame.setSpellCheckProvider(language, provider)​

  • language 字符串

    ¥language string

  • provider 对象

    ¥provider Object

    • spellCheck 函数

      ¥spellCheck Function

      • words 字符串[]

        ¥words string[]

      • callback 函数

        ¥callback Function

        • misspeltWords 字符串[]

          ¥misspeltWords string[]

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

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

使用 node-spellchecker 作为提供者的示例：

¥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 字符串

    ¥css string

  • options 对象（可选）

    ¥options Object (optional)

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

      ¥cssOrigin string (optional) - Can be 'user' or 'author'. Sets the cascade origin of the inserted stylesheet. Default is '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 字符串

    ¥key string

从当前网页中删除插入的 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 string

将 text 插入到焦点元素中。

¥Inserts text to the focused element.

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

  • code 字符串

    ¥code string

  • userGesture 布尔值（可选） - 默认为 false。

    ¥userGesture boolean (optional) - Default is false.

  • callback 功能（可选） - 脚本执行后调用。除非框架被挂起（例如显示模式警报），否则执行将是同步的，并且回调将在方法返回之前被调用。为了与此方法的旧版本兼容，错误参数是第二个。

    ¥callback Function (optional) - Called after script has been executed. Unless the frame is suspended (e.g. showing a modal alert), execution will be synchronous and the callback will be invoked before the method returns. For compatibility with an older version of this method, the error parameter is second.

    • result 任何

      ¥result Any

    • error 错误

      ¥error 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 范围内的值。

    ¥worldId Integer - The ID of the world to run the javascript in, 0 is the default main world (where content runs), 999 is the world used by Electron's contextIsolation feature. Accepts values in the range 1..536870911.

  • scripts WebSource[]

  • userGesture 布尔值（可选） - 默认为 false。

    ¥userGesture boolean (optional) - Default is false.

  • callback 功能（可选） - 脚本执行后调用。除非框架被挂起（例如显示模式警报），否则执行将是同步的，并且回调将在方法返回之前被调用。为了与此方法的旧版本兼容，错误参数是第二个。

    ¥callback Function (optional) - Called after script has been executed. Unless the frame is suspended (e.g. showing a modal alert), execution will be synchronous and the callback will be invoked before the method returns. For compatibility with an older version of this method, the error parameter is second.

    • result 任何

      ¥result Any

    • error 错误

      ¥error 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 范围。你可以在此处提供任何整数。

    ¥worldId Integer - The ID of the world to run the javascript in, 0 is the default world, 999 is the world used by Electron's contextIsolation feature. Chrome extensions reserve the range of IDs in [1 << 20, 1 << 29). You can provide any integer here.

  • info 对象

    ¥info Object

    • securityOrigin 字符串（可选） - 与世隔绝的安全起源。

      ¥securityOrigin string (optional) - Security origin for the isolated world.

    • csp 字符串（可选） - 孤立世界的内容安全策略。

      ¥csp string (optional) - Content Security Policy for the isolated world.

    • name 字符串（可选） - 孤立世界的名称。在开发工具中很有用。

      ¥name string (optional) - Name for isolated world. Useful in devtools.

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

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

[!NOTE] 如果指定了 csp，则也必须指定 securityOrigin。

¥[!NOTE] If the csp is specified, then the securityOrigin also has to be specified.

webFrame.getResourceUsage()​

返回 Object：

¥Returns Object:

返回一个描述 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 选择器。

    ¥selector string - CSS selector for a frame element.

返回 WebFrame | null - 如果 selector 没有选择帧或者该帧不在当前渲染进程中，则返回 selector、null 选择的 webFrame's 文档中的帧元素。

¥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 字符串

    ¥name string

返回 WebFrame | null - 如果不存在此类帧或者该帧不在当前渲染器进程中，则将返回 webFrame 的子级以及所提供的 name、null。

¥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）传递

    ¥routingId Integer - An Integer representing the unique frame id in the current renderer process. Routing IDs can be retrieved from WebFrame instances (webFrame.routingId) and are also passed by frame specific WebContents navigation events (e.g. did-frame-navigate)

返回 WebFrame | null - 如果没有找到，则有提供的 routingId、null。

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

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

¥Deprecated: Use the new webFrame.findFrameByToken API.

webFrame.findFrameByToken(frameToken)​

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

    ¥frameToken string - A string representing the unique frame id in the current renderer process. Frame tokens can be retrieved from WebFrame instances (webFrame.frameToken) and can also be retrieved from WebFrameMain instances using webFrameMain.frameToken.

返回 WebFrame | null - 如果没有找到，则有提供的 frameToken、null。

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

webFrame.isWordMisspelled(word)​

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

    ¥word string - The word to be spellchecked.

返回 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 字符串 - 拼写错误的单词。

    ¥word string - The misspelled 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 | null 代表 webFrame 的父框架，如果 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。

¥Deprecated: Use the new 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.