feat: add WebFrameMain detached property (#43473)
* feat: add WebFrameMain detached property fix: throw instead of returning null senderFrame test: detached frames fix: ensure IPCs of pending deletion RFHs are dispatched fix: lookup WFM by FTN ID to dispatch IPCs feat: add frame.isDestroyed() return null fix: return undefined docs: add null to all frame properties refactor: option c, return null and emit warning refactor: add routingId & processId to navigation events test: null frame property docs: clarify warning message better wording clarify null frame fix: browserwindow spec * maybe fix 🤷 * fix: use updated util #43722 * docs: add notice for frame change of behavior * docs: clarify why frame properties may be null * lint * wip * fix: content::FrameTreeNodeId lookup and converter * refactor: avoid holey array deoptimization --------- Co-authored-by: John Kleinschmidt <jkleinsc@electronjs.org>
This commit is contained in:
Sam Maddock
GitHub
parent
527efc01a4
commit
8b3d70a2a3
20 changed files with 410 additions and 126 deletions
|
|
@ -268,7 +268,8 @@ Returns:
|
|||
* `event` Event
|
||||
* `details` Object
|
||||
* `deviceList` [HIDDevice[]](structures/hid-device.md)
|
||||
* `frame` [WebFrameMain](web-frame-main.md)
|
||||
* `frame` [WebFrameMain](web-frame-main.md) | null - The frame initiating this event.
|
||||
May be `null` if accessed after the frame has either navigated or been destroyed.
|
||||
* `callback` Function
|
||||
* `deviceId` string | null (optional)
|
||||
|
||||
|
|
@ -332,7 +333,8 @@ Returns:
|
|||
* `event` Event
|
||||
* `details` Object
|
||||
* `device` [HIDDevice](structures/hid-device.md)
|
||||
* `frame` [WebFrameMain](web-frame-main.md)
|
||||
* `frame` [WebFrameMain](web-frame-main.md) | null - The frame initiating this event.
|
||||
May be `null` if accessed after the frame has either navigated or been destroyed.
|
||||
|
||||
Emitted after `navigator.hid.requestDevice` has been called and
|
||||
`select-hid-device` has fired if a new device becomes available before
|
||||
|
|
@ -347,7 +349,8 @@ Returns:
|
|||
* `event` Event
|
||||
* `details` Object
|
||||
* `device` [HIDDevice](structures/hid-device.md)
|
||||
* `frame` [WebFrameMain](web-frame-main.md)
|
||||
* `frame` [WebFrameMain](web-frame-main.md) | null - The frame initiating this event.
|
||||
May be `null` if accessed after the frame has either navigated or been destroyed.
|
||||
|
||||
Emitted after `navigator.hid.requestDevice` has been called and
|
||||
`select-hid-device` has fired if a device has been removed before the callback
|
||||
|
|
@ -473,7 +476,8 @@ Returns:
|
|||
* `event` Event
|
||||
* `details` Object
|
||||
* `port` [SerialPort](structures/serial-port.md)
|
||||
* `frame` [WebFrameMain](web-frame-main.md)
|
||||
* `frame` [WebFrameMain](web-frame-main.md) | null - The frame initiating this event.
|
||||
May be `null` if accessed after the frame has either navigated or been destroyed.
|
||||
* `origin` string - The origin that the device has been revoked from.
|
||||
|
||||
Emitted after `SerialPort.forget()` has been called. This event can be used
|
||||
|
|
@ -517,7 +521,8 @@ Returns:
|
|||
* `event` Event
|
||||
* `details` Object
|
||||
* `deviceList` [USBDevice[]](structures/usb-device.md)
|
||||
* `frame` [WebFrameMain](web-frame-main.md)
|
||||
* `frame` [WebFrameMain](web-frame-main.md) | null - The frame initiating this event.
|
||||
May be `null` if accessed after the frame has either navigated or been destroyed.
|
||||
* `callback` Function
|
||||
* `deviceId` string (optional)
|
||||
|
||||
|
|
@ -957,7 +962,8 @@ session.fromPartition('some-partition').setPermissionCheckHandler((webContents,
|
|||
|
||||
* `handler` Function | null
|
||||
* `request` Object
|
||||
* `frame` [WebFrameMain](web-frame-main.md) - Frame that is requesting access to media.
|
||||
* `frame` [WebFrameMain](web-frame-main.md) | null - Frame that is requesting access to media.
|
||||
May be `null` if accessed after the frame has either navigated or been destroyed.
|
||||
* `securityOrigin` String - Origin of the page making the request.
|
||||
* `videoRequested` Boolean - true if the web content requested a video stream.
|
||||
* `audioRequested` Boolean - true if the web content requested an audio stream.
|
||||
|
|
@ -1158,7 +1164,8 @@ app.whenReady().then(() => {
|
|||
pin displayed on the device.
|
||||
* `providePin`
|
||||
This prompt is requesting that a pin be provided for the device.
|
||||
* `frame` [WebFrameMain](web-frame-main.md)
|
||||
* `frame` [WebFrameMain](web-frame-main.md) | null - The frame initiating this handler.
|
||||
May be `null` if accessed after the frame has either navigated or been destroyed.
|
||||
* `pin` string (optional) - The pin value to verify if `pairingKind` is `confirmPin`.
|
||||
* `callback` Function
|
||||
* `response` Object
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@
|
|||
* `frameId` Integer - The ID of the renderer frame that sent this message
|
||||
* `returnValue` any - Set this to the value to be returned in a synchronous message
|
||||
* `sender` [WebContents](../web-contents.md) - Returns the `webContents` that sent the message
|
||||
* `senderFrame` [WebFrameMain](../web-frame-main.md) _Readonly_ - The frame that sent this message
|
||||
* `senderFrame` [WebFrameMain](../web-frame-main.md) | null _Readonly_ - The frame that sent this message. May be `null` if accessed after the frame has either navigated or been destroyed.
|
||||
* `ports` [MessagePortMain](../message-port-main.md)[] - A list of MessagePorts that were transferred with this message
|
||||
* `reply` Function - A function that will send an IPC message to the renderer frame that sent the original message that you are currently handling. You should use this method to "reply" to the sent message in order to guarantee the reply will go to the correct process and frame.
|
||||
* `channel` string
|
||||
|
|
|
|||
|
|
@ -3,4 +3,4 @@
|
|||
* `processId` Integer - The internal ID of the renderer process that sent this message
|
||||
* `frameId` Integer - The ID of the renderer frame that sent this message
|
||||
* `sender` [WebContents](../web-contents.md) - Returns the `webContents` that sent the message
|
||||
* `senderFrame` [WebFrameMain](../web-frame-main.md) _Readonly_ - The frame that sent this message
|
||||
* `senderFrame` [WebFrameMain](../web-frame-main.md) | null _Readonly_ - The frame that sent this message. May be `null` if accessed after the frame has either navigated or been destroyed.
|
||||
|
|
|
|||
|
|
@ -242,8 +242,9 @@ Returns:
|
|||
* `isSameDocument` boolean - This event does not fire for same document navigations using window.history api and reference fragment navigations.
|
||||
This property is always set to `false` for this event.
|
||||
* `isMainFrame` boolean - True if the navigation is taking place in a main frame.
|
||||
* `frame` WebFrameMain - The frame to be navigated.
|
||||
* `initiator` WebFrameMain (optional) - The frame which initiated the
|
||||
* `frame` WebFrameMain | null - The frame to be navigated.
|
||||
May be `null` if accessed after the frame has either navigated or been destroyed.
|
||||
* `initiator` WebFrameMain | null (optional) - The frame which initiated the
|
||||
navigation, which can be a parent frame (e.g. via `window.open` with a
|
||||
frame's name), or null if the navigation was not initiated by a frame. This
|
||||
can also be null if the initiating frame was deleted before the event was
|
||||
|
|
@ -275,8 +276,9 @@ Returns:
|
|||
* `isSameDocument` boolean - This event does not fire for same document navigations using window.history api and reference fragment navigations.
|
||||
This property is always set to `false` for this event.
|
||||
* `isMainFrame` boolean - True if the navigation is taking place in a main frame.
|
||||
* `frame` WebFrameMain - The frame to be navigated.
|
||||
* `initiator` WebFrameMain (optional) - The frame which initiated the
|
||||
* `frame` WebFrameMain | null - The frame to be navigated.
|
||||
May be `null` if accessed after the frame has either navigated or been destroyed.
|
||||
* `initiator` WebFrameMain | null (optional) - The frame which initiated the
|
||||
navigation, which can be a parent frame (e.g. via `window.open` with a
|
||||
frame's name), or null if the navigation was not initiated by a frame. This
|
||||
can also be null if the initiating frame was deleted before the event was
|
||||
|
|
@ -306,8 +308,9 @@ Returns:
|
|||
document. Examples of same document navigations are reference fragment
|
||||
navigations, pushState/replaceState, and same page history navigation.
|
||||
* `isMainFrame` boolean - True if the navigation is taking place in a main frame.
|
||||
* `frame` WebFrameMain - The frame to be navigated.
|
||||
* `initiator` WebFrameMain (optional) - The frame which initiated the
|
||||
* `frame` WebFrameMain | null - The frame to be navigated.
|
||||
May be `null` if accessed after the frame has either navigated or been destroyed.
|
||||
* `initiator` WebFrameMain | null (optional) - The frame which initiated the
|
||||
navigation, which can be a parent frame (e.g. via `window.open` with a
|
||||
frame's name), or null if the navigation was not initiated by a frame. This
|
||||
can also be null if the initiating frame was deleted before the event was
|
||||
|
|
@ -330,8 +333,9 @@ Returns:
|
|||
document. Examples of same document navigations are reference fragment
|
||||
navigations, pushState/replaceState, and same page history navigation.
|
||||
* `isMainFrame` boolean - True if the navigation is taking place in a main frame.
|
||||
* `frame` WebFrameMain - The frame to be navigated.
|
||||
* `initiator` WebFrameMain (optional) - The frame which initiated the
|
||||
* `frame` WebFrameMain | null - The frame to be navigated.
|
||||
May be `null` if accessed after the frame has either navigated or been destroyed.
|
||||
* `initiator` WebFrameMain | null (optional) - The frame which initiated the
|
||||
navigation, which can be a parent frame (e.g. via `window.open` with a
|
||||
frame's name), or null if the navigation was not initiated by a frame. This
|
||||
can also be null if the initiating frame was deleted before the event was
|
||||
|
|
@ -361,8 +365,9 @@ Returns:
|
|||
document. Examples of same document navigations are reference fragment
|
||||
navigations, pushState/replaceState, and same page history navigation.
|
||||
* `isMainFrame` boolean - True if the navigation is taking place in a main frame.
|
||||
* `frame` WebFrameMain - The frame to be navigated.
|
||||
* `initiator` WebFrameMain (optional) - The frame which initiated the
|
||||
* `frame` WebFrameMain | null - The frame to be navigated.
|
||||
May be `null` if accessed after the frame has either navigated or been destroyed.
|
||||
* `initiator` WebFrameMain | null (optional) - The frame which initiated the
|
||||
navigation, which can be a parent frame (e.g. via `window.open` with a
|
||||
frame's name), or null if the navigation was not initiated by a frame. This
|
||||
can also be null if the initiating frame was deleted before the event was
|
||||
|
|
@ -743,7 +748,8 @@ Returns:
|
|||
* `params` Object
|
||||
* `x` Integer - x coordinate.
|
||||
* `y` Integer - y coordinate.
|
||||
* `frame` WebFrameMain - Frame from which the context menu was invoked.
|
||||
* `frame` WebFrameMain | null - Frame from which the context menu was invoked.
|
||||
May be `null` if accessed after the frame has either navigated or been destroyed.
|
||||
* `linkURL` string - URL of the link that encloses the node the context menu
|
||||
was invoked on.
|
||||
* `linkText` string - Text associated with the link. May be an empty
|
||||
|
|
@ -1010,7 +1016,8 @@ Returns:
|
|||
|
||||
* `event` Event
|
||||
* `details` Object
|
||||
* `frame` WebFrameMain
|
||||
* `frame` WebFrameMain | null - The created frame.
|
||||
May be `null` if accessed after the frame has either navigated or been destroyed.
|
||||
|
||||
Emitted when the [mainFrame](web-contents.md#contentsmainframe-readonly), an `<iframe>`, or a nested `<iframe>` is loaded within the page.
|
||||
|
||||
|
|
|
|||
|
|
@ -97,6 +97,10 @@ this limitation.
|
|||
|
||||
Returns `boolean` - Whether the reload was initiated successfully. Only results in `false` when the frame has no history.
|
||||
|
||||
#### `frame.isDestroyed()`
|
||||
|
||||
Returns `boolean` - Whether the frame is destroyed.
|
||||
|
||||
#### `frame.send(channel, ...args)`
|
||||
|
||||
* `channel` string
|
||||
|
|
@ -231,6 +235,13 @@ A `string` representing the [visibility state](https://developer.mozilla.org/en-
|
|||
|
||||
See also how the [Page Visibility API](browser-window.md#page-visibility) is affected by other Electron APIs.
|
||||
|
||||
#### `frame.detached` _Readonly_
|
||||
|
||||
A `Boolean` representing whether the frame is detached from the frame tree. If a frame is accessed
|
||||
while the corresponding page is running any [unload][] listeners, it may become detached as the
|
||||
newly navigated page replaced it in the frame tree.
|
||||
|
||||
[SCA]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm
|
||||
[`postMessage`]: https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage
|
||||
[`MessagePortMain`]: message-port-main.md
|
||||
[unload]: https://developer.mozilla.org/en-US/docs/Web/API/Window/unload_event
|
||||
|
|
|
|||
|
|
@ -51,7 +51,8 @@ The following methods are available on instances of `WebRequest`:
|
|||
* `method` string
|
||||
* `webContentsId` Integer (optional)
|
||||
* `webContents` WebContents (optional)
|
||||
* `frame` WebFrameMain (optional)
|
||||
* `frame` WebFrameMain | null (optional) - Requesting frame.
|
||||
May be `null` if accessed after the frame has either navigated or been destroyed.
|
||||
* `resourceType` string - Can be `mainFrame`, `subFrame`, `stylesheet`, `script`, `image`, `font`, `object`, `xhr`, `ping`, `cspReport`, `media`, `webSocket` or `other`.
|
||||
* `referrer` string
|
||||
* `timestamp` Double
|
||||
|
|
@ -94,7 +95,8 @@ Some examples of valid `urls`:
|
|||
* `method` string
|
||||
* `webContentsId` Integer (optional)
|
||||
* `webContents` WebContents (optional)
|
||||
* `frame` WebFrameMain (optional)
|
||||
* `frame` WebFrameMain | null (optional) - Requesting frame.
|
||||
May be `null` if accessed after the frame has either navigated or been destroyed.
|
||||
* `resourceType` string - Can be `mainFrame`, `subFrame`, `stylesheet`, `script`, `image`, `font`, `object`, `xhr`, `ping`, `cspReport`, `media`, `webSocket` or `other`.
|
||||
* `referrer` string
|
||||
* `timestamp` Double
|
||||
|
|
@ -122,7 +124,8 @@ The `callback` has to be called with a `response` object.
|
|||
* `method` string
|
||||
* `webContentsId` Integer (optional)
|
||||
* `webContents` WebContents (optional)
|
||||
* `frame` WebFrameMain (optional)
|
||||
* `frame` WebFrameMain | null (optional) - Requesting frame.
|
||||
May be `null` if accessed after the frame has either navigated or been destroyed.
|
||||
* `resourceType` string - Can be `mainFrame`, `subFrame`, `stylesheet`, `script`, `image`, `font`, `object`, `xhr`, `ping`, `cspReport`, `media`, `webSocket` or `other`.
|
||||
* `referrer` string
|
||||
* `timestamp` Double
|
||||
|
|
@ -142,7 +145,8 @@ response are visible by the time this listener is fired.
|
|||
* `method` string
|
||||
* `webContentsId` Integer (optional)
|
||||
* `webContents` WebContents (optional)
|
||||
* `frame` WebFrameMain (optional)
|
||||
* `frame` WebFrameMain | null (optional) - Requesting frame.
|
||||
May be `null` if accessed after the frame has either navigated or been destroyed.
|
||||
* `resourceType` string - Can be `mainFrame`, `subFrame`, `stylesheet`, `script`, `image`, `font`, `object`, `xhr`, `ping`, `cspReport`, `media`, `webSocket` or `other`.
|
||||
* `referrer` string
|
||||
* `timestamp` Double
|
||||
|
|
@ -173,7 +177,8 @@ The `callback` has to be called with a `response` object.
|
|||
* `method` string
|
||||
* `webContentsId` Integer (optional)
|
||||
* `webContents` WebContents (optional)
|
||||
* `frame` WebFrameMain (optional)
|
||||
* `frame` WebFrameMain | null (optional) - Requesting frame.
|
||||
May be `null` if accessed after the frame has either navigated or been destroyed.
|
||||
* `resourceType` string - Can be `mainFrame`, `subFrame`, `stylesheet`, `script`, `image`, `font`, `object`, `xhr`, `ping`, `cspReport`, `media`, `webSocket` or `other`.
|
||||
* `referrer` string
|
||||
* `timestamp` Double
|
||||
|
|
@ -197,7 +202,8 @@ and response headers are available.
|
|||
* `method` string
|
||||
* `webContentsId` Integer (optional)
|
||||
* `webContents` WebContents (optional)
|
||||
* `frame` WebFrameMain (optional)
|
||||
* `frame` WebFrameMain | null (optional) - Requesting frame.
|
||||
May be `null` if accessed after the frame has either navigated or been destroyed.
|
||||
* `resourceType` string - Can be `mainFrame`, `subFrame`, `stylesheet`, `script`, `image`, `font`, `object`, `xhr`, `ping`, `cspReport`, `media`, `webSocket` or `other`.
|
||||
* `referrer` string
|
||||
* `timestamp` Double
|
||||
|
|
@ -222,7 +228,8 @@ redirect is about to occur.
|
|||
* `method` string
|
||||
* `webContentsId` Integer (optional)
|
||||
* `webContents` WebContents (optional)
|
||||
* `frame` WebFrameMain (optional)
|
||||
* `frame` WebFrameMain | null (optional) - Requesting frame.
|
||||
May be `null` if accessed after the frame has either navigated or been destroyed.
|
||||
* `resourceType` string - Can be `mainFrame`, `subFrame`, `stylesheet`, `script`, `image`, `font`, `object`, `xhr`, `ping`, `cspReport`, `media`, `webSocket` or `other`.
|
||||
* `referrer` string
|
||||
* `timestamp` Double
|
||||
|
|
@ -245,7 +252,8 @@ completed.
|
|||
* `method` string
|
||||
* `webContentsId` Integer (optional)
|
||||
* `webContents` WebContents (optional)
|
||||
* `frame` WebFrameMain (optional)
|
||||
* `frame` WebFrameMain | null (optional) - Requesting frame.
|
||||
May be `null` if accessed after the frame has either navigated or been destroyed.
|
||||
* `resourceType` string - Can be `mainFrame`, `subFrame`, `stylesheet`, `script`, `image`, `font`, `object`, `xhr`, `ping`, `cspReport`, `media`, `webSocket` or `other`.
|
||||
* `referrer` string
|
||||
* `timestamp` Double
|
||||
|
|
|
|||
|
|
@ -14,6 +14,34 @@ This document uses the following convention to categorize breaking changes:
|
|||
|
||||
## Planned Breaking API Changes (33.0)
|
||||
|
||||
### Behavior Changed: frame properties may retrieve detached WebFrameMain instances or none at all
|
||||
|
||||
APIs which provide access to a `WebFrameMain` instance may return an instance
|
||||
with `frame.detached` set to `true`, or possibly return `null`.
|
||||
|
||||
When a frame performs a cross-origin navigation, it enters into a detached state
|
||||
in which it's no longer attached to the page. In this state, it may be running
|
||||
[unload](https://developer.mozilla.org/en-US/docs/Web/API/Window/unload_event)
|
||||
handlers prior to being deleted. In the event of an IPC sent during this state,
|
||||
`frame.detached` will be set to `true` with the frame being destroyed shortly
|
||||
thereafter.
|
||||
|
||||
When receiving an event, it's important to access WebFrameMain properties
|
||||
immediately upon being received. Otherwise, it's not guaranteed to point to the
|
||||
same webpage as when received. To avoid misaligned expectations, Electron will
|
||||
return `null` in the case of late access where the webpage has changed.
|
||||
|
||||
```ts
|
||||
ipcMain.on('unload-event', (event) => {
|
||||
event.senderFrame; // ✅ accessed immediately
|
||||
});
|
||||
|
||||
ipcMain.on('unload-event', async (event) => {
|
||||
await crossOriginNavigationPromise;
|
||||
event.senderFrame; // ❌ returns `null` due to late access
|
||||
});
|
||||
```
|
||||
|
||||
### Behavior Changed: custom protocol URL handling on Windows
|
||||
|
||||
Due to changes made in Chromium to support [Non-Special Scheme URLs](http://bit.ly/url-non-special), custom protocol URLs that use Windows file paths will no longer work correctly with the deprecated `protocol.registerFileProtocol` and the `baseURLForDataURL` property on `BrowserWindow.loadURL`, `WebContents.loadURL`, and `<webview>.loadURL`. `protocol.handle` will also not work with these types of URLs but this is not a change since it has always worked that way.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue