From f9aa42d6157fbf557fb4d2d7167700ebefd889a0 Mon Sep 17 00:00:00 2001 From: Anny Yang Date: Mon, 11 Nov 2024 17:37:45 +0000 Subject: [PATCH 1/7] docs: add blog post for migrating to WebContentsView --- blog/authors.yml | 5 ++ blog/electron-30-0.md | 2 +- blog/migrate-to-webcontentsview.md | 86 ++++++++++++++++++++++++++++++ 3 files changed, 92 insertions(+), 1 deletion(-) create mode 100644 blog/migrate-to-webcontentsview.md diff --git a/blog/authors.yml b/blog/authors.yml index 6791bccd4..4d167879b 100644 --- a/blog/authors.yml +++ b/blog/authors.yml @@ -73,6 +73,11 @@ VerteDinde: url: https://github.com/VerteDinde image_url: https://github.com/VerteDinde.png?size=96 +yangannyx: + name: yangannyx + url: https://github.com/yangannyx + image_url: https://github.com/yangannyx.png?size=96 + zcbenz: name: zcbenz url: https://github.com/zcbenz diff --git a/blog/electron-30-0.md b/blog/electron-30-0.md index 9e0c7a179..25e7a1215 100644 --- a/blog/electron-30-0.md +++ b/blog/electron-30-0.md @@ -23,7 +23,7 @@ If you have any feedback, please share it with us on [Twitter](https://twitter.c - ASAR Integrity fuse now supported on Windows ([#40504](https://github.com/electron/electron/pull/40504)) - Existing apps with ASAR Integrity enabled may not work on Windows if not configured correctly. Apps using Electron packaging tools should upgrade to `@electron/packager@18.3.1` or `@electron/forge@7.4.0`. - Take a look at our [ASAR Integrity tutorial](https://www.electronjs.org/docs/latest/tutorial/asar-integrity) for more information. -- Added [`WebContentsView`](https://www.electronjs.org/docs/latest/api/web-contents-view) and [`BaseWindow`](https://www.electronjs.org/docs/latest/api/base-window) main process modules, deprecating & replacing `BrowserView` ([#35658](https://github.com/electron/electron/pull/35658)) +- Added [`WebContentsView`](https://www.electronjs.org/docs/latest/api/web-contents-view) and [`BaseWindow`](https://www.electronjs.org/docs/latest/api/base-window) main process modules, deprecating & replacing `BrowserView` ([#35658](https://github.com/electron/electron/pull/35658)). Learn more about how to migrate from `BrowserView` to `WebContentsView` in [this blog post](https://www.electronjs.org/blog/migrate-to-webcontentsview). - `BrowserView` is now a shim over `WebContentsView` and the old implementation has been removed. - See [our Web Embeds documentation](https://www.electronjs.org/docs/latest/tutorial/web-embeds) for a comparison of the new `WebContentsView` API to other similar APIs. - Implemented support for the [File System API](https://developer.mozilla.org/en-US/docs/Web/API/File_System_API) ([#41827](https://github.com/electron/electron/commit/cf1087badd437906f280373decb923733a8523e6)) diff --git a/blog/migrate-to-webcontentsview.md b/blog/migrate-to-webcontentsview.md new file mode 100644 index 000000000..c6a95d5cd --- /dev/null +++ b/blog/migrate-to-webcontentsview.md @@ -0,0 +1,86 @@ +--- +title: Migrating from BrowserView to WebContentsView +date: 2024-11-11T00:00:00.000Z +authors: yangannyx +slug: migrate-to-webcontentsview +tags: [community] +--- + +`BrowserView` has been deprecated since [Electron 30](http://www.electronjs.org/blog/electron-30-0) and is replaced by `WebContentView`. Thankfully, migrating is fairly painless. + +--- + +Electron is moving from [`BrowserView`](https://www.electronjs.org/docs/latest/api/browser-view) to [`WebContentsView`](https://www.electronjs.org/docs/latest/api/web-contents-view) to align with Chromium’s UI framework, the [Views API](https://www.chromium.org/chromium-os/developer-library/guides/views/intro/). `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. + +Developers familiar with BrowserWindows and BrowserViews should note that `BrowserWindow` and `WebContentsView` are subclasses inheriting from the [`BaseWindow`](https://www.electronjs.org/docs/latest/api/base-window) and [`View`](https://www.electronjs.org/docs/latest/api/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. Upgrade Electron to 30.0.0 or higher + +:::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 can be found in the release notes for each major version on the Electron Blog. +::: + +### 2. Familiarize yourself with where your application uses 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 +For the most part, each instance where your app instantiates new BrowserViews can be migrated in isolation from the others. +::: + +### 3. Migrate each usage of `BrowserView` + +1. Migrate the instantiation. This should be fairly straight forward because [WebContentsView](https://www.electronjs.org/docs/latest/api/web-contents-view#new-webcontentsviewoptions) and [BrowserView’s](https://www.electronjs.org/docs/latest/api/browser-view#new-browserviewoptions-experimental-deprecated) constructors have essentially the same shape. Both accept [WebPreferences](https://www.electronjs.org/docs/latest/api/structures/web-preferences) via the `webPreferences` param. + +```diff +- this.tabBar = new BrowserView({ ++ this.tabBar = new WebContentsView({ +``` + +2. Migrate where the `BrowserView` gets added to its parent window. + +```diff +- this.browserWindow.addBrowserView(this.tabBar) ++ this.browserWindow.contentView.addChildView(this.tabBar); +``` + +3. Migrate `BrowserView` instance method calls on the parent window. + +| Old Method | New Method | Notes | +| ----------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------ | +| `win.setBrowserView` | `win.contentView.removeChildView` + `win.contentView.addChildView` | | +| `win.getBrowserView` | `win.contentView.children` | | +| `win.removeBrowserView` | `win.contentView.removeChildView` | | +| `win.setTopBrowserView` | `win.contentView.addChildView` | Calling `addChildView` on an existing view reorders it to the top. | +| `win.getBrowserViews` | `win.contentView.children` | | + +4. Migrate the `setAutoResize` instance method to a resize listener. + +```diff +- 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 +All existing usage of `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 + +Congrats, you’ve migrated onto WebContentsViews! 🎉 From 6710a90306be431a02c9ea04391c97cf807e346f Mon Sep 17 00:00:00 2001 From: Anny Yang Date: Tue, 12 Nov 2024 10:39:59 +0000 Subject: [PATCH 2/7] docs: fix relativelink --- blog/electron-30-0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/blog/electron-30-0.md b/blog/electron-30-0.md index 25e7a1215..f6f1479f6 100644 --- a/blog/electron-30-0.md +++ b/blog/electron-30-0.md @@ -23,7 +23,7 @@ If you have any feedback, please share it with us on [Twitter](https://twitter.c - ASAR Integrity fuse now supported on Windows ([#40504](https://github.com/electron/electron/pull/40504)) - Existing apps with ASAR Integrity enabled may not work on Windows if not configured correctly. Apps using Electron packaging tools should upgrade to `@electron/packager@18.3.1` or `@electron/forge@7.4.0`. - Take a look at our [ASAR Integrity tutorial](https://www.electronjs.org/docs/latest/tutorial/asar-integrity) for more information. -- Added [`WebContentsView`](https://www.electronjs.org/docs/latest/api/web-contents-view) and [`BaseWindow`](https://www.electronjs.org/docs/latest/api/base-window) main process modules, deprecating & replacing `BrowserView` ([#35658](https://github.com/electron/electron/pull/35658)). Learn more about how to migrate from `BrowserView` to `WebContentsView` in [this blog post](https://www.electronjs.org/blog/migrate-to-webcontentsview). +- Added [`WebContentsView`](https://www.electronjs.org/docs/latest/api/web-contents-view) and [`BaseWindow`](https://www.electronjs.org/docs/latest/api/base-window) main process modules, deprecating & replacing `BrowserView` ([#35658](https://github.com/electron/electron/pull/35658)). Learn more about how to migrate from `BrowserView` to `WebContentsView` in [this blog post](./migrate-to-webcontentsview). - `BrowserView` is now a shim over `WebContentsView` and the old implementation has been removed. - See [our Web Embeds documentation](https://www.electronjs.org/docs/latest/tutorial/web-embeds) for a comparison of the new `WebContentsView` API to other similar APIs. - Implemented support for the [File System API](https://developer.mozilla.org/en-US/docs/Web/API/File_System_API) ([#41827](https://github.com/electron/electron/commit/cf1087badd437906f280373decb923733a8523e6)) From 9746dde32ae255ed723e9239e761517bd8d522fd Mon Sep 17 00:00:00 2001 From: Anny Yang Date: Tue, 12 Nov 2024 10:57:01 +0000 Subject: [PATCH 3/7] fixes lint --- blog/migrate-to-webcontentsview.md | 80 +++++++++++++++--------------- 1 file changed, 40 insertions(+), 40 deletions(-) diff --git a/blog/migrate-to-webcontentsview.md b/blog/migrate-to-webcontentsview.md index c6a95d5cd..08ee52c9f 100644 --- a/blog/migrate-to-webcontentsview.md +++ b/blog/migrate-to-webcontentsview.md @@ -32,54 +32,54 @@ For the most part, each instance where your app instantiates new BrowserViews ca ### 3. Migrate each usage of `BrowserView` -1. Migrate the instantiation. This should be fairly straight forward because [WebContentsView](https://www.electronjs.org/docs/latest/api/web-contents-view#new-webcontentsviewoptions) and [BrowserView’s](https://www.electronjs.org/docs/latest/api/browser-view#new-browserviewoptions-experimental-deprecated) constructors have essentially the same shape. Both accept [WebPreferences](https://www.electronjs.org/docs/latest/api/structures/web-preferences) via the `webPreferences` param. +1. Migrate the instantiation. This should be fairly straight forward because [WebContentsView](https://www.electronjs.org/docs/latest/api/web-contents-view#new-webcontentsviewoptions) and [BrowserView’s](https://www.electronjs.org/docs/latest/api/browser-view#new-browserviewoptions-experimental-deprecated) constructors have essentially the same shape. Both accept [WebPreferences](https://www.electronjs.org/docs/latest/api/structures/web-preferences) via the `webPreferences` param. -```diff -- this.tabBar = new BrowserView({ -+ this.tabBar = new WebContentsView({ -``` + ```diff + - this.tabBar = new BrowserView({ + + this.tabBar = new WebContentsView({ + ``` -2. Migrate where the `BrowserView` gets added to its parent window. +2. Migrate where the `BrowserView` gets added to its parent window. -```diff -- this.browserWindow.addBrowserView(this.tabBar) -+ this.browserWindow.contentView.addChildView(this.tabBar); -``` + ```diff + - this.browserWindow.addBrowserView(this.tabBar) + + this.browserWindow.contentView.addChildView(this.tabBar); + ``` -3. Migrate `BrowserView` instance method calls on the parent window. +3. Migrate `BrowserView` instance method calls on the parent window. -| Old Method | New Method | Notes | -| ----------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------ | -| `win.setBrowserView` | `win.contentView.removeChildView` + `win.contentView.addChildView` | | -| `win.getBrowserView` | `win.contentView.children` | | -| `win.removeBrowserView` | `win.contentView.removeChildView` | | -| `win.setTopBrowserView` | `win.contentView.addChildView` | Calling `addChildView` on an existing view reorders it to the top. | -| `win.getBrowserViews` | `win.contentView.children` | | + | Old Method | New Method | Notes | + | ----------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------ | + | `win.setBrowserView` | `win.contentView.removeChildView` + `win.contentView.addChildView` | | + | `win.getBrowserView` | `win.contentView.children` | | + | `win.removeBrowserView` | `win.contentView.removeChildView` | | + | `win.setTopBrowserView` | `win.contentView.addChildView` | Calling `addChildView` on an existing view reorders it to the top. | + | `win.getBrowserViews` | `win.contentView.children` | | 4. Migrate the `setAutoResize` instance method to a resize listener. -```diff -- 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 -All existing usage of `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! -::: + ```diff + - 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 + All existing usage of `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 From 4eea4042a8ab02282d3ceffef5faf197f46b0f37 Mon Sep 17 00:00:00 2001 From: Anny Yang Date: Thu, 14 Nov 2024 02:58:55 -0800 Subject: [PATCH 4/7] Update blog/migrate-to-webcontentsview.md Co-authored-by: Erick Zhao --- blog/migrate-to-webcontentsview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/blog/migrate-to-webcontentsview.md b/blog/migrate-to-webcontentsview.md index 08ee52c9f..608965fd2 100644 --- a/blog/migrate-to-webcontentsview.md +++ b/blog/migrate-to-webcontentsview.md @@ -19,7 +19,7 @@ Developers familiar with BrowserWindows and BrowserViews should note that `Brows ### 1. Upgrade Electron to 30.0.0 or higher :::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 can be found in the release notes for each major version on the Electron Blog. +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 can be found in the release notes for each major version on the Electron Blog. ::: ### 2. Familiarize yourself with where your application uses BrowserViews From 7a281b77cdd6a2a285890f1a743c4a3a57536ddc Mon Sep 17 00:00:00 2001 From: Anny Yang Date: Thu, 14 Nov 2024 02:59:03 -0800 Subject: [PATCH 5/7] Update blog/migrate-to-webcontentsview.md Co-authored-by: Erick Zhao --- blog/migrate-to-webcontentsview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/blog/migrate-to-webcontentsview.md b/blog/migrate-to-webcontentsview.md index 608965fd2..e53673628 100644 --- a/blog/migrate-to-webcontentsview.md +++ b/blog/migrate-to-webcontentsview.md @@ -32,7 +32,7 @@ For the most part, each instance where your app instantiates new BrowserViews ca ### 3. Migrate each usage of `BrowserView` -1. Migrate the instantiation. This should be fairly straight forward because [WebContentsView](https://www.electronjs.org/docs/latest/api/web-contents-view#new-webcontentsviewoptions) and [BrowserView’s](https://www.electronjs.org/docs/latest/api/browser-view#new-browserviewoptions-experimental-deprecated) constructors have essentially the same shape. Both accept [WebPreferences](https://www.electronjs.org/docs/latest/api/structures/web-preferences) via the `webPreferences` param. +1. Migrate the instantiation. This should be fairly straightforward because [WebContentsView](https://www.electronjs.org/docs/latest/api/web-contents-view#new-webcontentsviewoptions) and [BrowserView’s](https://www.electronjs.org/docs/latest/api/browser-view#new-browserviewoptions-experimental-deprecated) constructors have essentially the same shape. Both accept [WebPreferences](https://www.electronjs.org/docs/latest/api/structures/web-preferences) via the `webPreferences` param. ```diff - this.tabBar = new BrowserView({ From 7668963eee322ea4862719e7c0b5df140f467083 Mon Sep 17 00:00:00 2001 From: Anny Yang Date: Thu, 14 Nov 2024 11:33:15 +0000 Subject: [PATCH 6/7] addressing feedback --- blog/electron-30-0.md | 2 +- blog/migrate-to-webcontentsview.md | 4 +++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/blog/electron-30-0.md b/blog/electron-30-0.md index f6f1479f6..e1a87ac31 100644 --- a/blog/electron-30-0.md +++ b/blog/electron-30-0.md @@ -23,7 +23,7 @@ If you have any feedback, please share it with us on [Twitter](https://twitter.c - ASAR Integrity fuse now supported on Windows ([#40504](https://github.com/electron/electron/pull/40504)) - Existing apps with ASAR Integrity enabled may not work on Windows if not configured correctly. Apps using Electron packaging tools should upgrade to `@electron/packager@18.3.1` or `@electron/forge@7.4.0`. - Take a look at our [ASAR Integrity tutorial](https://www.electronjs.org/docs/latest/tutorial/asar-integrity) for more information. -- Added [`WebContentsView`](https://www.electronjs.org/docs/latest/api/web-contents-view) and [`BaseWindow`](https://www.electronjs.org/docs/latest/api/base-window) main process modules, deprecating & replacing `BrowserView` ([#35658](https://github.com/electron/electron/pull/35658)). Learn more about how to migrate from `BrowserView` to `WebContentsView` in [this blog post](./migrate-to-webcontentsview). +- Added [`WebContentsView`](https://www.electronjs.org/docs/latest/api/web-contents-view) and [`BaseWindow`](https://www.electronjs.org/docs/latest/api/base-window) main process modules, deprecating & replacing `BrowserView` ([#35658](https://github.com/electron/electron/pull/35658)). Learn more about how to migrate from `BrowserView` to `WebContentsView` in [this blog post](http://www.electronjs.org/blog/migrate-to-webcontentsview). - `BrowserView` is now a shim over `WebContentsView` and the old implementation has been removed. - See [our Web Embeds documentation](https://www.electronjs.org/docs/latest/tutorial/web-embeds) for a comparison of the new `WebContentsView` API to other similar APIs. - Implemented support for the [File System API](https://developer.mozilla.org/en-US/docs/Web/API/File_System_API) ([#41827](https://github.com/electron/electron/commit/cf1087badd437906f280373decb923733a8523e6)) diff --git a/blog/migrate-to-webcontentsview.md b/blog/migrate-to-webcontentsview.md index e53673628..54e7217a8 100644 --- a/blog/migrate-to-webcontentsview.md +++ b/blog/migrate-to-webcontentsview.md @@ -19,7 +19,7 @@ Developers familiar with BrowserWindows and BrowserViews should note that `Brows ### 1. Upgrade Electron to 30.0.0 or higher :::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 can be found in the release notes for each major version on the Electron Blog. +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](https://www.electronjs.org/docs/latest/breaking-changes) as well as in the release notes for each major version on the Electron Blog. ::: ### 2. Familiarize yourself with where your application uses BrowserViews @@ -83,4 +83,6 @@ For the most part, each instance where your app instantiates new BrowserViews ca ### 4. Test and commit your changes +Running into issues? Check the [WebContentsView](https://github.com/electron/electron/labels/component%2FWebContentsView) 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! + Congrats, you’ve migrated onto WebContentsViews! 🎉 From 8175baef90c20016ec457d99585aac114cd5d3bc Mon Sep 17 00:00:00 2001 From: Anny Yang Date: Thu, 14 Nov 2024 13:29:47 +0000 Subject: [PATCH 7/7] adds file ending --- blog/electron-30-0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/blog/electron-30-0.md b/blog/electron-30-0.md index e1a87ac31..3b515fc8a 100644 --- a/blog/electron-30-0.md +++ b/blog/electron-30-0.md @@ -23,7 +23,7 @@ If you have any feedback, please share it with us on [Twitter](https://twitter.c - ASAR Integrity fuse now supported on Windows ([#40504](https://github.com/electron/electron/pull/40504)) - Existing apps with ASAR Integrity enabled may not work on Windows if not configured correctly. Apps using Electron packaging tools should upgrade to `@electron/packager@18.3.1` or `@electron/forge@7.4.0`. - Take a look at our [ASAR Integrity tutorial](https://www.electronjs.org/docs/latest/tutorial/asar-integrity) for more information. -- Added [`WebContentsView`](https://www.electronjs.org/docs/latest/api/web-contents-view) and [`BaseWindow`](https://www.electronjs.org/docs/latest/api/base-window) main process modules, deprecating & replacing `BrowserView` ([#35658](https://github.com/electron/electron/pull/35658)). Learn more about how to migrate from `BrowserView` to `WebContentsView` in [this blog post](http://www.electronjs.org/blog/migrate-to-webcontentsview). +- Added [`WebContentsView`](https://www.electronjs.org/docs/latest/api/web-contents-view) and [`BaseWindow`](https://www.electronjs.org/docs/latest/api/base-window) main process modules, deprecating & replacing `BrowserView` ([#35658](https://github.com/electron/electron/pull/35658)). Learn more about how to migrate from `BrowserView` to `WebContentsView` in [this blog post](./migrate-to-webcontentsview.md). - `BrowserView` is now a shim over `WebContentsView` and the old implementation has been removed. - See [our Web Embeds documentation](https://www.electronjs.org/docs/latest/tutorial/web-embeds) for a comparison of the new `WebContentsView` API to other similar APIs. - Implemented support for the [File System API](https://developer.mozilla.org/en-US/docs/Web/API/File_System_API) ([#41827](https://github.com/electron/electron/commit/cf1087badd437906f280373decb923733a8523e6))