从 BrowserView 迁移到 WebContentsView

发表于 分类于 阅读次数： 本文字数： 1.2k 阅读时长 ≈ 4 分钟

BrowserView has been deprecated since Electron 30 and is replaced by WebContentView. Thankfully, migrating is fairly painless.
BrowserView 自 Electron 30 起已被弃用，取而代之的是 WebContentView 。值得庆幸的是，迁移过程非常简单。

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.
为了与 Chromium 的用户界面框架 “视图 API”（Views API）保持一致，Electron 正在从 BrowserView 转向 WebContentsView 。 WebContentsView 提供了与 Chromium 渲染管道直接关联的可重用视图，简化了未来的升级，并为开发者将非网页 UI 元素集成到 Electron 应用程序中提供了可能性。通过采用 WebContentsView ，应用程序不仅为即将到来的更新做好了准备，而且从长远来看，还能从降低代码复杂性和减少潜在错误中获益。

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

Migration steps 迁移步骤

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

warning 警告

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.
电子版可能包含会影响你的应用程序的破坏性更改。在进行其余迁移之前，最好先在你的应用程序上测试和登陆 Electron 升级。每个 Electron 主要版本的破坏性更改列表可以在这里找到，也可以在 Electron 博客上每个主要版本的发布说明中找到。

2.熟悉应用程序使用 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.
一种方法是在代码库中搜索 new BrowserView( 。这应该能让你了解你的应用程序是如何使用 BrowserViews 的，以及有多少调用站点需要迁移。

tip 提示

For the most part, each instance where your app instantiates new BrowserViews can be migrated in isolation from the others.
在大多数情况下，应用程序实例化新 BrowserView 的每个实例都可以独立于其他实例进行迁移。

3.迁移每处使用到 BrowserView 的地方

  1. 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.
    迁移实例化。这应该相当简单，因为 WebContentsView 和 BrowserView 的构造函数形状基本相同。两者都通过 webPreferences 参数接受 WebPreferences。

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

    INFO

    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:
    默认情况下， WebContentsView 实例为白色背景，而 BrowserView 实例为透明背景。要在 WebContentsView 中获得透明背景，可将其背景颜色设置为 RGBA 十六进制值，并将 alpha（不透明）通道设置为 00 ：

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

  2. Migrate where the BrowserView gets added to its parent window.
    迁移 BrowserView 被添加到其父窗口的位置。

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

  3. Migrate BrowserView instance method calls on the parent window.
    迁移父窗口上的 BrowserView 实例方法调用。

    Old Method 旧方法New Method 新方法Notes 说明
    win.setBrowserViewwin.contentView.removeChildView + win.contentView.addChildView
    win.getBrowserViewwin.contentView.children
    win.removeBrowserViewwin.contentView.removeChildView
    win.setTopBrowserViewwin.contentView.addChildViewCalling addChildView on an existing view reorders it to the top. 在现有视图上调用 addChildView 会将其重新排序到顶部。
    win.getBrowserViewswin.contentView.children

  4. Migrate the setAutoResize instance method to a resize listener.
    将 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,
    +    });
    +  });

4.测试并提交更改

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!
遇到问题？查看 Electron 问题跟踪器上的 WebContentsView 标签，看看你遇到的问题是否已被报告。如果你没有在那里看到你的问题，请随时添加一个新的错误报告。包括测试案例 gists 将帮助我们更好地分流你的问题！

Congrats, you’ve migrated onto WebContentsViews! 🎉
恭喜您，您已经迁移到 WebContentsViews 上！🎉