跳转到主要内容

从 BrowserView 迁移到 WebContentsView

·阅读时长 4 分钟

Electron 30 起,BrowserView 已被弃用,并由 WebContentView 取代。幸运的是,迁移过程相当轻松。


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

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

迁移步骤

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

警告

Electron 的版本发布可能包含会影响您应用程序的重大变更。在进行本次迁移的其余步骤之前,最好先在您的应用程序上测试并完成 Electron 的升级。每个 Electron 主要版本的重大变更列表可以在这里以及 Electron 博客上每个主要版本的发布说明中找到。

2. 熟悉您的应用程序在何处使用了 BrowserViews

一种方法是在您的代码库中搜索 new BrowserView(。这应该能让您了解您的应用程序是如何使用 BrowserViews 的,以及有多少调用点需要迁移。

提示

在大多数情况下,您的应用程序中实例化新 BrowserViews 的每个地方都可以与其他地方隔离开来,独立进行迁移。

3. 迁移每个 BrowserView 的用法

  1. 迁移实例化过程。这应该相当直接,因为 WebContentsViewBrowserView 的构造函数结构基本相同。两者都通过 webPreferences 参数接受 WebPreferences

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

    默认情况下,WebContentsView 实例化时背景为白色,而 BrowserView 实例化时背景为透明。要在 WebContentsView 中获得透明背景,请将其背景颜色设置为一个 alpha(不透明度)通道为 00 的 RGBA 十六进制值。

    + this.webContentsView.setBackgroundColor("#00000000");
  2. 迁移将 BrowserView 添加到其父窗口的代码。

    - this.browserWindow.addBrowserView(this.tabBar)
    + this.browserWindow.contentView.addChildView(this.tabBar);
  3. 迁移父窗口上的 BrowserView 实例方法调用。

    旧方法新方法备注
    win.setBrowserViewwin.contentView.removeChildView + win.contentView.addChildView
    win.getBrowserViewwin.contentView.children
    win.removeBrowserViewwin.contentView.removeChildView
    win.setTopBrowserViewwin.contentView.addChildView对一个已存在的视图调用 addChildView 会将其重新排序到顶部。
    win.getBrowserViewswin.contentView.children
  4. setAutoResize 实例方法迁移到一个 resize 监听器。

    - 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.setBoundsbrowserView.getBoundsbrowserView.setBackgroundColor 都不需要迁移,它们应该可以与 WebContentsView 实例直接兼容!

4. 测试并提交您的更改

遇到问题了吗?请查看 Electron 问题跟踪器上的 WebContentsView 标签,看看您遇到的问题是否已被报告。如果您在那里没有看到您的问题,请随时提交一个新的错误报告。附上测试用例的 gists 将有助于我们更好地分类您的问题!

恭喜,您已成功迁移到 WebContentsViews!🎉