Skip to main content

从 BrowserView 迁移到 WebContentsView

· 5 min read
yangannyx

BrowserView 自 Electron 30 起已被弃用，并被 WebContentView 替代。所幸的是，迁移相对非常简单。

Electron 正在从 BrowserView 移动到 WebContentsView，以与 Chromium 的 UI 框架 Views API 对齐。WebContentsView 提供了一个可重用的视图，直接与 Chromium 的渲染管线相关联，从而简化了未来的升级，并为开发者在 Electron 应用中集成非 Web UI 元素提供了可能。通过采用 WebContentsView，应用不仅为即将到来的更新做好准备，还能在长期中受益于更低的代码复杂性和更少的潜在 bug。

🌐 Electron is moving from BrowserView to WebContentsView to align with Chromium’s UI framework, the Views API. WebContentsView offers a reusable view directly tied to Chromium’s rendering pipeline, simplifying future upgrades and opening up the possibility for developers to integrate non-web UI elements to their Electron apps. By adopting WebContentsView, applications are not only prepared for upcoming updates but also benefit from reduced code complexity and fewer potential bugs in the long run.

熟悉 BrowserWindows 和 BrowserViews 的开发者应注意，BrowserWindow 和 WebContentsView 是分别继承自 BaseWindow 和 View 基类的子类。要全面了解可用的实例变量和方法，请务必查阅这些基类的文档。

🌐 Developers familiar with BrowserWindows and BrowserViews should note that BrowserWindow and WebContentsView are subclasses inheriting from the BaseWindow and View base classes, respectively. To fully understand the available instance variables and methods, be sure to consult the documentation for these base classes.

迁移步骤​

🌐 Migration steps

1. 将 Electron 升级到 30.0.0 或更高版本​

🌐 1. Upgrade Electron to 30.0.0 or higher

warning

Electron 的版本发布可能包含影响你应用的重大更改。在进行其余迁移之前，建议先在你的应用上测试并完成 Electron 升级。每个 Electron 主版本的重大更改列表可以在 这里 查看，也可以在 Electron 博客的每个主版本发布说明中找到。

2. 熟悉你的应用使用 BrowserViews 的位置​

🌐 2. Familiarize yourself with where your application uses BrowserViews

一种方法是搜索你的代码库中的 new BrowserView(。这应该可以让你了解你的应用如何使用 BrowserViews 以及需要迁移的调用点数量。

🌐 One way to do this is to search your codebase for new BrowserView(. This should give you a sense for how your application is using BrowserViews and how many call sites need to be migrated.

tip

在大多数情况下，你的应用实例化新 BrowserView 的每个实例都可以独立于其他实例进行迁移。

3. 迁移每个 BrowserView 的使用​

🌐 3. Migrate each usage of BrowserView

  1. 迁移实例化。这应该相当简单，因为 WebContentsView 和 BrowserView 的构造函数本质上形状相同。两者都通过 webPreferences 参数接受 WebPreferences。

    - this.tabBar = new BrowserView({
    + this.tabBar = new WebContentsView({
    info

    默认情况下，WebContentsView 会以白色背景实例化，而 BrowserView 会以透明背景实例化。

要在 WebContentsView 中获得透明背景，请将其背景颜色设置为带有 alpha（不透明度）通道并设置为 00 的 RGBA 十六进制值：

+ this.webContentsView.setBackgroundColor("#00000000");

:::

  1. 迁移 BrowserView 被添加到其父窗口的位置。

    - this.browserWindow.addBrowserView(this.tabBar)
    + this.browserWindow.contentView.addChildView(this.tabBar);

  2. 迁移父窗口上的 BrowserView 实例方法调用。

    | 旧方法 | 新方法 | 备注 | | ----------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------- | | win.setBrowserView | win.contentView.removeChildView + win.contentView.addChildView | | | win.getBrowserView | win.contentView.children | | | win.removeBrowserView | win.contentView.removeChildView | | | win.setTopBrowserView | win.contentView.addChildView | 在现有视图上调用 addChildView 会将其重新排列到顶部。 | | win.getBrowserViews | win.contentView.children | |

  3. 将 setAutoResize 实例方法迁移到调整大小监听器。

    - this.browserView.setAutoResize({
    -   vertical: true,
    - })

    + this.browserWindow.on('resize', () => {
    +   if (!this.browserWindow || !this.webContentsView) {
    +     return;
    +   }
    +   const bounds = this.browserWindow.getBounds();
    +   this.webContentsView.setBounds({
    +     x: 0,
    +     y: 0,
    +     width: bounds.width,
    +     height: bounds.height,
    +    });
    +  });

    :::提示 所有现有的 browserView.webContents 用法以及实例方法 browserView.setBounds、browserView.getBounds 和 browserView.setBackgroundColor 都不需要迁移，并且应该能够直接在 WebContentsView 实例上使用！ :::

4. 测试并提交你的更改​

🌐 4. Test and commit your changes

遇到问题了吗？请查看 Electron 的问题跟踪器上的 WebContentsView 标签，看看你遇到的问题是否已被报告。如果没有看到你的问题，欢迎提交新的错误报告。包括测试用例的 Gist 会帮助我们更好地分类和处理你的问题！

🌐 Running into issues? Check the WebContentsView tag on Electron's issue tracker to see if the issue you're encountering has been reported. If you don't see your issue there, feel free to add a new bug report. Including testcase gists will help us better triage your issue!

恭喜，你已经迁移到 WebContentsViews 了！🎉

🌐 Congrats, you’ve migrated onto WebContentsViews! 🎉