跳转到主要内容

从 BrowserView 迁移到 WebContentsView

·阅读时长 4 分钟

BrowserViewElectron 30 起已弃用,并被 WebContentsView 取代。幸运的是,迁移过程相当轻松。


Electron 正在从 BrowserView 迁移到 WebContentsView,以与 Chromium 的 UI 框架 Views API 对齐。WebContentsView 提供了一个直接与 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 中获得透明背景,请将其背景颜色设置为 RGBA 十六进制值,并将 alpha(不透明度)通道设置为 00

    + 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 标签,看看您遇到的问题是否已被报告。如果您在那里没有看到您的问题,请随时添加新的 bug 报告。包含测试用例 gist 将有助于我们更好地分类您的问题!

恭喜,您已迁移到 WebContentsViews!🎉