chore: remove deprecated 'new-window' event

electron · Aug 8, 2022 · 9aee851 · 9aee851
1 parent 76431ac
commit 9aee851
Show file tree

Hide file tree

Showing 14 changed files with 32 additions and 673 deletions.
diff --git a/docs/api/structures/new-window-web-contents-event.md b/docs/api/structures/new-window-web-contents-event.md
diff --git a/docs/api/web-contents.md b/docs/api/web-contents.md
@@ -156,64 +156,6 @@ Returns:
 
 Emitted when page receives favicon urls.
 
-#### Event: 'new-window' _Deprecated_
-
-Returns:
-
-* `event` NewWindowWebContentsEvent
-* `url` string
-* `frameName` string
-* `disposition` string - Can be `default`, `foreground-tab`, `background-tab`,
-  `new-window`, `save-to-disk` and `other`.
-* `options` BrowserWindowConstructorOptions - The options which will be used for creating the new
-  [`BrowserWindow`](browser-window.md).
-* `additionalFeatures` string[] - The non-standard features (features not handled
-  by Chromium or Electron) given to `window.open()`. Deprecated, and will now
-  always be the empty array `[]`.
-* `referrer` [Referrer](structures/referrer.md) - The referrer that will be
-  passed to the new window. May or may not result in the `Referer` header being
-  sent, depending on the referrer policy.
-* `postBody` [PostBody](structures/post-body.md) (optional) - The post data that
-  will be sent to the new window, along with the appropriate headers that will
-  be set. If no post data is to be sent, the value will be `null`. Only defined
-  when the window is being created by a form that set `target=_blank`.
-
-Deprecated in favor of [`webContents.setWindowOpenHandler`](web-contents.md#contentssetwindowopenhandlerhandler).
-
-Emitted when the page requests to open a new window for a `url`. It could be
-requested by `window.open` or an external link like `<a target='_blank'>`.
-
-By default a new `BrowserWindow` will be created for the `url`.
-
-Calling `event.preventDefault()` will prevent Electron from automatically creating a
-new [`BrowserWindow`](browser-window.md). If you call `event.preventDefault()` and manually create a new
-[`BrowserWindow`](browser-window.md) then you must set `event.newGuest` to reference the new [`BrowserWindow`](browser-window.md)
-instance, failing to do so may result in unexpected behavior. For example:
-
-```javascript
-myBrowserWindow.webContents.on('new-window', (event, url, frameName, disposition, options, additionalFeatures, referrer, postBody) => {
-  event.preventDefault()
-  const win = new BrowserWindow({
-    webContents: options.webContents, // use existing webContents if provided
-    show: false
-  })
-  win.once('ready-to-show', () => win.show())
-  if (!options.webContents) {
-    const loadOptions = {
-      httpReferrer: referrer
-    }
-    if (postBody != null) {
-      const { data, contentType, boundary } = postBody
-      loadOptions.postData = postBody.data
-      loadOptions.extraHeaders = `content-type: ${contentType}; boundary=${boundary}`
-    }
-
-    win.loadURL(url, loadOptions) // existing webContents will be navigated automatically
-  }
-  event.newGuest = win
-})
-```
-
 #### Event: 'did-create-window'
 
 Returns:

diff --git a/docs/api/webview-tag.md b/docs/api/webview-tag.md
@@ -805,33 +805,6 @@ const requestId = webview.findInPage('test')
 console.log(requestId)
 ```
 
-### Event: 'new-window'
-
-Returns:
-
-* `url` string
-* `frameName` string
-* `disposition` string - Can be `default`, `foreground-tab`, `background-tab`,
-  `new-window`, `save-to-disk` and `other`.
-* `options` BrowserWindowConstructorOptions - The options which should be used for creating the new
-  [`BrowserWindow`](browser-window.md).
-
-Fired when the guest page attempts to open a new browser window.
-
-The following example code opens the new url in system's default browser.
-
-```javascript
-const { shell } = require('electron')
-const webview = document.querySelector('webview')
-
-webview.addEventListener('new-window', async (e) => {
-  const protocol = (new URL(e.url)).protocol
-  if (protocol === 'http:' || protocol === 'https:') {
-    await shell.openExternal(e.url)
-  }
-})
-```
-
 ### Event: 'will-navigate'
 
 Returns:

diff --git a/docs/breaking-changes.md b/docs/breaking-changes.md
@@ -12,6 +12,24 @@ This document uses the following convention to categorize breaking changes:
 * **Deprecated:** An API was marked as deprecated. The API will continue to function, but will emit a deprecation warning, and will be removed in a future release.
 * **Removed:** An API or feature was removed, and is no longer supported by Electron.
 
+## Planned Breaking API Changes (21.0)
+
+### Removed: WebContents `new-window` event
+
+The `new-window` event of WebContents has been removed. It is replaced by [`webContents.setWindowOpenHandler()`](api/web-contents.md#contentssetwindowopenhandlerhandler).
+
+```js
+// Removed in Electron 21
+webContents.on('new-window', (event) => {
+  event.preventDefault()
+})
+
+// Replace with
+webContents.setWindowOpenHandler((details) => {
+  return { action: 'deny' }
+})
+```
+
 ## Planned Breaking API Changes (20.0)
 
 ### Behavior Changed: V8 Memory Cage enabled

diff --git a/filenames.auto.gni b/filenames.auto.gni
@@ -98,7 +98,6 @@ auto_filenames = {
     "docs/api/structures/mime-typed-buffer.md",
     "docs/api/structures/mouse-input-event.md",
     "docs/api/structures/mouse-wheel-input-event.md",
-    "docs/api/structures/new-window-web-contents-event.md",
     "docs/api/structures/notification-action.md",
     "docs/api/structures/notification-response.md",
     "docs/api/structures/payment-discount.md",

diff --git a/lib/browser/api/web-contents.ts b/lib/browser/api/web-contents.ts
@@ -670,7 +670,6 @@ WebContents.prototype._init = function () {
       const options = result.browserWindowConstructorOptions;
       if (!event.defaultPrevented) {
         openGuestWindow({
-          event,
           embedder: event.sender,
           disposition,
           referrer,
@@ -717,13 +716,7 @@ WebContents.prototype._init = function () {
           transparent: windowOpenOverriddenOptions.transparent,
           ...windowOpenOverriddenOptions.webPreferences
         } : undefined;
-        // TODO(zcbenz): The features string is parsed twice: here where it is
-        // passed to C++, and in |makeBrowserWindowOptions| later where it is
-        // not actually used since the WebContents is created here.
-        // We should be able to remove the latter once the |new-window| event
-        // is removed.
         const { webPreferences: parsedWebPreferences } = parseFeatures(rawFeatures);
-        // Parameters should keep same with |makeBrowserWindowOptions|.
         const webPreferences = makeWebPreferences({
           embedder: event.sender,
           insecureParsedWebPreferences: parsedWebPreferences,
@@ -750,7 +743,6 @@ WebContents.prototype._init = function () {
       }
 
       openGuestWindow({
-        event,
         embedder: event.sender,
         guest: webContents,
         overrideBrowserWindowOptions: overriddenOptions,

diff --git a/lib/browser/guest-view-manager.ts b/lib/browser/guest-view-manager.ts
@@ -22,13 +22,6 @@ const supportedWebViewEvents = Object.keys(webViewEvents);
 const guestInstances = new Map<number, GuestInstance>();
 const embedderElementsMap = new Map<string, number>();
 
-function sanitizeOptionsForGuest (options: Record<string, any>) {
-  const ret = { ...options };
-  // WebContents values can't be sent over IPC.
-  delete ret.webContents;
-  return ret;
-}
-
 function makeWebPreferences (embedder: Electron.WebContents, params: Record<string, any>) {
   // parse the 'webpreferences' attribute string, if set
   // this uses the same parsing rules as window.open uses for its features
@@ -156,15 +149,6 @@ const createGuest = function (embedder: Electron.WebContents, embedderFrameId: n
     });
   }
 
-  guest.on('new-window', function (event, url, frameName, disposition, options) {
-    sendToEmbedder(IPC_MESSAGES.GUEST_VIEW_INTERNAL_DISPATCH_EVENT, 'new-window', {
-      url,
-      frameName,
-      disposition,
-      options: sanitizeOptionsForGuest(options)
-    });
-  });
-
   // Dispatch guest's IPC messages to embedder.
   guest.on('ipc-message-host' as any, function (event: Electron.IpcMainEvent, channel: string, args: any[]) {
     sendToEmbedder(IPC_MESSAGES.GUEST_VIEW_INTERNAL_DISPATCH_EVENT, 'ipc-message', {

diff --git a/lib/browser/guest-window-manager.ts b/lib/browser/guest-window-manager.ts
@@ -5,7 +5,7 @@
  * out-of-process (cross-origin) are created here. "Embedder" roughly means
  * "parent."
  */
-import { BrowserWindow, deprecate } from 'electron/main';
+import { BrowserWindow } from 'electron/main';
 import type { BrowserWindowConstructorOptions, Referrer, WebContents, LoadURLOptions } from 'electron/main';
 import { parseFeatures } from '@electron/internal/browser/parse-features-string';
 
@@ -24,13 +24,8 @@ const getGuestWindowByFrameName = (name: string) => frameNamesToWindow.get(name)
 /**
  * `openGuestWindow` is called to create and setup event handling for the new
  * window.
- *
- * Until its removal in 12.0.0, the `new-window` event is fired, allowing the
- * user to preventDefault() on the passed event (which ends up calling
- * DestroyWebContents).
  */
-export function openGuestWindow ({ event, embedder, guest, referrer, disposition, postData, overrideBrowserWindowOptions, windowOpenArgs, outlivesOpener }: {
-  event: { sender: WebContents, defaultPrevented: boolean },
+export function openGuestWindow ({ embedder, guest, referrer, disposition, postData, overrideBrowserWindowOptions, windowOpenArgs, outlivesOpener }: {
   embedder: WebContents,
   guest?: WebContents,
   referrer: Referrer,
@@ -41,23 +36,14 @@ export function openGuestWindow ({ event, embedder, guest, referrer, disposition
   outlivesOpener: boolean,
 }): BrowserWindow | undefined {
   const { url, frameName, features } = windowOpenArgs;
-  const browserWindowOptions = makeBrowserWindowOptions({
-    embedder,
-    features,
-    overrideOptions: overrideBrowserWindowOptions
-  });
-
-  const didCancelEvent = emitDeprecatedNewWindowEvent({
-    event,
-    embedder,
-    guest,
-    browserWindowOptions,
-    windowOpenArgs,
-    disposition,
-    postData,
-    referrer
-  });
-  if (didCancelEvent) return;
+  const { options: parsedOptions } = parseFeatures(features);
+  const browserWindowOptions = {
+    show: true,
+    width: 800,
+    height: 600,
+    ...parsedOptions,
+    ...overrideBrowserWindowOptions
+  };
 
   // To spec, subsequent window.open calls with the same frame name (`target` in
   // spec parlance) will reuse the previous window.
@@ -134,68 +120,6 @@ const handleWindowLifecycleEvents = function ({ embedder, guest, frameName, outl
   }
 };
 
-/**
- * Deprecated in favor of `webContents.setWindowOpenHandler` and
- * `did-create-window` in 11.0.0. Will be removed in 12.0.0.
- */
-function emitDeprecatedNewWindowEvent ({ event, embedder, guest, windowOpenArgs, browserWindowOptions, disposition, referrer, postData }: {
-  event: { sender: WebContents, defaultPrevented: boolean, newGuest?: BrowserWindow },
-  embedder: WebContents,
-  guest?: WebContents,
-  windowOpenArgs: WindowOpenArgs,
-  browserWindowOptions: BrowserWindowConstructorOptions,
-  disposition: string,
-  referrer: Referrer,
-  postData?: PostData,
-}): boolean {
-  const { url, frameName } = windowOpenArgs;
-  const isWebViewWithPopupsDisabled = embedder.getType() === 'webview' && embedder.getLastWebPreferences()!.disablePopups;
-  const postBody = postData ? {
-    data: postData,
-    ...parseContentTypeFormat(postData)
-  } : null;
-
-  if (embedder.listenerCount('new-window') > 0) {
-    deprecate.log('The new-window event is deprecated and will be removed. Please use contents.setWindowOpenHandler() instead.');
-  }
-
-  embedder.emit(
-    'new-window',
-    event,
-    url,
-    frameName,
-    disposition,
-    {
-      ...browserWindowOptions,
-      webContents: guest
-    },
-    [], // additionalFeatures
-    referrer,
-    postBody
-  );
-
-  const { newGuest } = event;
-  if (isWebViewWithPopupsDisabled) return true;
-  if (event.defaultPrevented) {
-    if (newGuest) {
-      if (guest === newGuest.webContents) {
-        // The webContents is not changed, so set defaultPrevented to false to
-        // stop the callers of this event from destroying the webContents.
-        event.defaultPrevented = false;
-      }
-
-      handleWindowLifecycleEvents({
-        embedder: event.sender,
-        guest: newGuest,
-        frameName,
-        outlivesOpener: false
-      });
-    }
-    return true;
-  }
-  return false;
-}
-
 // Security options that child windows will always inherit from parent windows
 const securityWebPreferences: { [key: string]: boolean } = {
   contextIsolation: true,
@@ -207,31 +131,6 @@ const securityWebPreferences: { [key: string]: boolean } = {
   enableWebSQL: false
 };
 
-function makeBrowserWindowOptions ({ embedder, features, overrideOptions }: {
-  embedder: WebContents,
-  features: string,
-  overrideOptions?: BrowserWindowConstructorOptions,
-}) {
-  const { options: parsedOptions, webPreferences: parsedWebPreferences } = parseFeatures(features);
-
-  return {
-    show: true,
-    width: 800,
-    height: 600,
-    ...parsedOptions,
-    ...overrideOptions,
-    // Note that for normal code path an existing WebContents created by
-    // Chromium will be used, with web preferences parsed in the
-    // |-will-add-new-contents| event.
-    // The |webPreferences| here is only used by the |new-window| event.
-    webPreferences: makeWebPreferences({
-      embedder,
-      insecureParsedWebPreferences: parsedWebPreferences,
-      secureOverrideWebPreferences: overrideOptions && overrideOptions.webPreferences
-    })
-  } as Electron.BrowserViewConstructorOptions;
-}
-
 export function makeWebPreferences ({ embedder, secureOverrideWebPreferences = {}, insecureParsedWebPreferences: parsedWebPreferences = {} }: {
   embedder: WebContents,
   insecureParsedWebPreferences?: ReturnType<typeof parseFeatures>['webPreferences'],