mirrors/electron
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages 1 Wiki Activity Actions 1

feat: add will-frame-navigate event (#34418)

Browse source 
* feat: add will-navigate-in-frame event to webContents

* docs: add documentation for webview will-frame-navigate event

* feat: Eliminate isInPlace argument from will-frame-navigate event

* fix: Fire will-frame-navigate before will-navigate

* feat: send will-frame-navigate with a WebFrameMain in the event details

* docs: Update WebContents docs for new API signature

* feat: Add custom event forwarding for <webview> will-frame-navigate

* fix: wrap WebFrameMain so it can be sent as an event

* test: update webContents and <webview> tests to match new signatures

* chore: undo unnecessary change

* fix: don't switch will-navigate to use EmitNavigationEventDetails

* test: clean up will-navigate and will-frame-navigate tests for <webview>

* chore: apply lint fixes

* chore: move GetRenderFrameHost helper into anonymous namespace

* docs: auto-generate WillFrameNavigateDetails rather than defining it manually

* test: Update <webview> tests to actually pass under new spec runner

* docs: Add section explaining relationship between various nav events

* test: Add some tests to ensure navigation event order doesn't silently change

* test: Always monitor all nav events to ensure unexpected ones don't fire

* test: Add test to verify in-page navigation event order

* feat: Change to new style where extra params are exposed as event props

* fix: Remove unused EmitNavigationEventDetails

* fix: Update tests to use new async helpers

* docs: Rename and reorder sections documenting navigation events

---------

Co-authored-by: Milan Burda <milan.burda@gmail.com>
This commit is contained in:
Will Anderson 2023-03-28 07:55:41 -07:00 • committed by GitHub
parent 2e1f803f37
commit 2b9dae4b06
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
8 changed files with 540 additions and 14 deletions
Download patch file Download diff file Expand all files Collapse all files

60
docs/api/web-contents.md
View file

@ -19,6 +19,36 @@ const contents = win.webContents
console.log(contents)
```
## Navigation Events
Several events can be used to monitor navigations as they occur within a `webContents`.
### Document Navigations
When a `webContents` navigates to another page (as opposed to an [in-page navigation](web-contents.md#in-page-navigation)), the following events will be fired.
* [`did-start-navigation`](web-contents.md#event-did-start-navigation)
* [`will-frame-navigate`](web-contents.md#event-will-frame-navigate)
* [`will-navigate`](web-contents.md#event-will-navigate) (only fired when main frame navigates)
* [`will-redirect`](web-contents.md#event-will-redirect) (only fired when a redirect happens during navigation)
* [`did-redirect-navigation`](web-contents.md#event-did-redirect-navigation) (only fired when a redirect happens during navigation)
* [`did-frame-navigate`](web-contents.md#event-did-frame-navigate)
* [`did-navigate`](web-contents.md#event-did-navigate) (only fired when main frame navigates)
Subsequent events will not fire if `event.preventDefault()` is called on any of the cancellable events.
### In-page Navigation
In-page navigations don't cause the page to reload, but instead navigate to a location within the current page. These events are not cancellable. For an in-page navigations, the following events will fire in this order:
* [`did-start-navigation`](web-contents.md#event-did-start-navigation)
* [`did-navigate-in-page`](web-contents.md#event-did-navigate-in-page)
### Frame Navigation
The [`will-navigate`](web-contents.md#event-will-navigate) and [`did-navigate`](web-contents.md#event-did-navigate) events only fire when the [mainFrame](web-contents.md#contentsmainframe-readonly) navigates.
If you want to also observe navigations in `<iframe>`s, use [`will-frame-navigate`](web-contents.md#event-will-frame-navigate) and [`did-frame-navigate`](web-contents.md#event-did-frame-navigate) events.
## Methods
These methods can be accessed from the `webContents` module:
@ -225,7 +255,7 @@ Returns:
* `frameProcessId` Integer _Deprecated_
* `frameRoutingId` Integer _Deprecated_
Emitted when a user or the page wants to start navigation. It can happen when
Emitted when a user or the page wants to start navigation on the main frame. It can happen when
the `window.location` object is changed or a user clicks a link in the page.
This event will not emit when the navigation is started programmatically with
@ -237,6 +267,34 @@ this purpose.
Calling `event.preventDefault()` will prevent the navigation.
#### Event: 'will-frame-navigate'
Returns:
* `details` Event<>
* `url` string - The URL the frame is navigating to.
* `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
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
emitted.
Emitted when a user or the page wants to start navigation in any frame. It can happen when
the `window.location` object is changed or a user clicks a link in the page.
Unlike `will-navigate`, `will-frame-navigate` is fired when the main frame or any of its subframes attempts to navigate. When the navigation event comes from the main frame, `isMainFrame` will be `true`.
This event will not emit when the navigation is started programmatically with
APIs like `webContents.loadURL` and `webContents.back`.
It is also not emitted for in-page navigations, such as clicking anchor links
or updating the `window.location.hash`. Use `did-navigate-in-page` event for
this purpose.
Calling `event.preventDefault()` will prevent the navigation.
#### Event: 'did-start-navigation'
Returns: