Skip to main content

从 BrowserView 迁移到 WebContentsView

· 7 min read
yangannyx

BrowserView 自 Electron 30 起已弃用，并由 WebContentView 取代。值得庆幸的是，迁移过程相当轻松。

¥BrowserView has been deprecated since Electron 30 and is replaced by WebContentView. Thankfully, migrating is fairly painless.

Electron 正在从 BrowserView 迁移到 WebContentsView，以与 Chromium 的 UI 框架 Views API 保持一致。WebContentsView 提供了一个可复用的视图，直接与 Chromium 的渲染管道绑定，简化了未来的升级，并为开发者提供了将非 Web UI 元素集成到其 Electron 应用的可能性。通过采用 WebContentsView，应用不仅可以为即将到来的更新做好准备，还可以受益于更少的从长远来看，这将降低代码复杂性并减少潜在错误。

¥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 或更高版本​

¥ Upgrade Electron to 30.0.0 or higher

警告

Electron 版本可能包含影响你应用的重大更改。在继续进行其余迁移之前，建议先在你的应用上测试并安装 Electron 升级。Electron 各主要版本的重大变更列表可在 此处 以及 Electron 博客上各主要版本的发行说明中找到。

¥Electron releases may contain breaking changes that affect your application. It’s a good idea to test and land the Electron upgrade on your app first before proceeding with the rest of this migration. A list of breaking changes for each Electron major version can be found here as well as in the release notes for each major version on the Electron Blog.

2. 熟悉你的应用在何处使用 BrowserViews​

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

提示

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

¥For the most part, each instance where your app instantiates new BrowserViews can be migrated in isolation from the others.

3. 迁移 BrowserView 的每个用法​

¥ Migrate each usage of BrowserView

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

    ¥Migrate the instantiation. This should be fairly straightforward because WebContentsView and BrowserView’s constructors have essentially the same shape. Both accept WebPreferences via the webPreferences param.

   - this.tabBar = new BrowserView({
   + this.tabBar = new WebContentsView({
信息

默认情况下，WebContentsView 实例化时背景为白色，而 BrowserView 实例化时背景为透明。要在 WebContentsView 中获得透明背景，请将其背景颜色设置为 RGBA 十六进制值，并将 Alpha（不透明度）通道设置为 00：

¥By default, WebContentsView instantiates with a white background, while BrowserView instantiates with a transparent background. To get a transparent background in WebContentsView, set its background color to an RGBA hex value with an alpha (opaqueness) channel set to 00:

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

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

    ¥Migrate where the BrowserView gets added to its parent window.

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

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

    ¥Migrate BrowserView instance method calls on the parent window.

    旧方法新方法备注：
    win.setBrowserViewwin.contentView.removeChildView + win.contentView.addChildView
    win.getBrowserViewwin.contentView.children
    win.removeBrowserViewwin.contentView.removeChildView
    win.setTopBrowserViewwin.contentView.addChildView在现有视图上调用 addChildView 会将其重新排序到顶部。
    win.getBrowserViewswin.contentView.children

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

    ¥Migrate the setAutoResize instance method to a resize listener.

   - 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,
   +    });
   +  });
tip

browserView.webContents and instance methods browserView.setBounds, browserView.getBounds , and browserView.setBackgroundColor do not need to be migrated and should work with a WebContentsView instance out of the box! :::所有现有用法

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

¥ Test and commit your changes

遇到问题？查看 Electron 问题跟踪器上的 WebContentsView 标签，看看你遇到的问题是否已被报告。如果你在那里没有看到你的问题，请随时添加新的错误报告。包含测试用例要点将有助于我们更好地分类你的问题！

¥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! 🎉