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..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)) +- 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)) diff --git a/blog/migrate-to-webcontentsview.md b/blog/migrate-to-webcontentsview.md new file mode 100644 index 000000000..54e7217a8 --- /dev/null +++ b/blog/migrate-to-webcontentsview.md @@ -0,0 +1,88 @@ +--- +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 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 + +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 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({ + + 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 + +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! 🎉