docs: add docs API history (#43362)

feat: add API history
2024-08-19 14:13:55 -07:00 · 2024-08-19 14:13:55 -07:00 · 9e421e8f43
commit 9e421e8f43
parent 2471ebf39c
12 changed files with 718 additions and 1 deletions
--- a/docs/api/base-window.md
+++ b/docs/api/base-window.md
@ -926,6 +926,17 @@ win.setSheetOffset(toolbarRect.height)

 #### `win.flashFrame(flag)`

+<!--
+```YAML history
+added:
+  - pr-url: https://github.com/electron/electron/pull/35658
+changes:
+  - pr-url: https://github.com/electron/electron/pull/41391
+    description: "`window.flashFrame(bool)` will flash dock icon continuously on macOS"
+    breaking-changes-header: behavior-changed-windowflashframebool-will-flash-dock-icon-continuously-on-macos
+```
+-->
+
 * `flag` boolean

 Starts or stops flashing the window to attract user's attention.
--- a/docs/api/browser-view.md
+++ b/docs/api/browser-view.md
@ -1,5 +1,13 @@
 # BrowserView

+<!--
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/35658
+    breaking-changes-header: deprecated-browserview
+```
+-->
+
 > **Note**
 > The `BrowserView` class is deprecated, and replaced by the new
 > [`WebContentsView`](web-contents-view.md) class.
@ -11,6 +19,14 @@ relative to its owning window. It is meant to be an alternative to the

 ## Class: BrowserView

+<!--
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/35658
+    breaking-changes-header: deprecated-browserview
+```
+-->
+
 > Create and control views.

 > **Note**
@ -40,6 +56,14 @@ app.whenReady().then(() => {

 ### `new BrowserView([options])` _Experimental_ _Deprecated_

+<!--
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/35658
+    breaking-changes-header: deprecated-browserview
+```
+-->
+
 * `options` Object (optional)
  * `webPreferences` [WebPreferences](structures/web-preferences.md?inline) (optional) - Settings of web page's features.

@ -49,6 +73,14 @@ Objects created with `new BrowserView` have the following properties:

 #### `view.webContents` _Experimental_ _Deprecated_

+<!--
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/35658
+    breaking-changes-header: deprecated-browserview
+```
+-->
+
 A [`WebContents`](web-contents.md) object owned by this view.

 ### Instance Methods
@ -57,6 +89,18 @@ Objects created with `new BrowserView` have the following instance methods:

 #### `view.setAutoResize(options)` _Experimental_ _Deprecated_

+<!--
+```YAML history
+changes:
+  - pr-url: https://github.com/electron/electron/pull/35658
+    description: "Standardized auto-resizing behavior across all platforms"
+    breaking-changes-header: behavior-changed-browserviewsetautoresize-behavior-on-macos
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/35658
+    breaking-changes-header: deprecated-browserview
+```
+-->
+
 * `options` Object
  * `width` boolean (optional) - If `true`, the view's width will grow and shrink together
    with the window. `false` by default.
@ -69,18 +113,42 @@ Objects created with `new BrowserView` have the following instance methods:

 #### `view.setBounds(bounds)` _Experimental_ _Deprecated_

+<!--
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/35658
+    breaking-changes-header: deprecated-browserview
+```
+-->
+
 * `bounds` [Rectangle](structures/rectangle.md)

 Resizes and moves the view to the supplied bounds relative to the window.

 #### `view.getBounds()` _Experimental_ _Deprecated_

+<!--
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/35658
+    breaking-changes-header: deprecated-browserview
+```
+-->
+
 Returns [`Rectangle`](structures/rectangle.md)

 The `bounds` of this BrowserView instance as `Object`.

 #### `view.setBackgroundColor(color)` _Experimental_ _Deprecated_

+<!--
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/35658
+    breaking-changes-header: deprecated-browserview
+```
+-->
+
 * `color` string - Color in Hex, RGB, ARGB, HSL, HSLA or named CSS color format. The alpha channel is
  optional for the hex type.

--- a/docs/api/browser-window.md
+++ b/docs/api/browser-window.md
@ -1051,6 +1051,15 @@ win.setSheetOffset(toolbarRect.height)

 #### `win.flashFrame(flag)`

+<!--
+```YAML history
+changes:
+  - pr-url: https://github.com/electron/electron/pull/41391
+    description: "`window.flashFrame(bool)` will flash dock icon continuously on macOS"
+    breaking-changes-header: behavior-changed-windowflashframebool-will-flash-dock-icon-continuously-on-macos
+```
+-->
+
 * `flag` boolean

 Starts or stops flashing the window to attract user's attention.
--- a/docs/api/context-bridge.md
+++ b/docs/api/context-bridge.md
@ -1,5 +1,14 @@
 # contextBridge

+<!--
+```YAML history
+changes:
+  - pr-url: https://github.com/electron/electron/pull/40330
+    description: "`ipcRenderer` can no longer be sent over the `contextBridge`"
+    breaking-changes-header: behavior-changed-ipcrenderer-can-no-longer-be-sent-over-the-contextbridge
+```
+-->
+
 > Create a safe, bi-directional, synchronous bridge across isolated contexts

 Process: [Renderer](../glossary.md#renderer-process)
--- a/docs/api/ipc-renderer.md
+++ b/docs/api/ipc-renderer.md
@ -7,6 +7,15 @@ hide_title: false

 # ipcRenderer

+<!--
+```YAML history
+changes:
+  - pr-url: https://github.com/electron/electron/pull/40330
+    description: "`ipcRenderer` can no longer be sent over the `contextBridge`"
+    breaking-changes-header: behavior-changed-ipcrenderer-can-no-longer-be-sent-over-the-contextbridge
+```
+-->
+
 > Communicate asynchronously from a renderer process to the main process.

 Process: [Renderer](../glossary.md#renderer-process)
--- a/docs/api/native-image.md
+++ b/docs/api/native-image.md
@ -257,6 +257,15 @@ data.

 #### `image.toDataURL([options])`

+<!--
+```YAML history
+changes:
+  - pr-url: https://github.com/electron/electron/pull/41752
+    description: "`nativeImage.toDataURL` will preserve PNG colorspace"
+    breaking-changes-header: behavior-changed-nativeimagetodataurl-will-preserve-png-colorspace
+```
+-->
+
 * `options` Object (optional)
  * `scaleFactor` Number (optional) - Defaults to 1.0.

--- a/docs/api/protocol.md
+++ b/docs/api/protocol.md
@ -189,6 +189,15 @@ Returns `boolean` - Whether `scheme` is already handled.

 ### `protocol.registerFileProtocol(scheme, handler)` _Deprecated_

+<!--
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/36674
+    description: "`protocol.register*Protocol` and `protocol.intercept*Protocol` methods have been replaced with `protocol.handle`"
+    breaking-changes-header: deprecated-protocolunregisterinterceptbufferstringstreamfilehttpprotocol-and-protocolisprotocolregisteredintercepted
+```
+-->
+
 * `scheme` string
 * `handler` Function
  * `request` [ProtocolRequest](structures/protocol-request.md)
@ -210,6 +219,15 @@ from protocols that follow the "generic URI syntax" like `file:`.

 ### `protocol.registerBufferProtocol(scheme, handler)` _Deprecated_

+<!--
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/36674
+    description: "`protocol.register*Protocol` and `protocol.intercept*Protocol` methods have been replaced with `protocol.handle`"
+    breaking-changes-header: deprecated-protocolunregisterinterceptbufferstringstreamfilehttpprotocol-and-protocolisprotocolregisteredintercepted
+```
+-->
+
 * `scheme` string
 * `handler` Function
  * `request` [ProtocolRequest](structures/protocol-request.md)
@ -234,6 +252,15 @@ protocol.registerBufferProtocol('atom', (request, callback) => {

 ### `protocol.registerStringProtocol(scheme, handler)` _Deprecated_

+<!--
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/36674
+    description: "`protocol.register*Protocol` and `protocol.intercept*Protocol` methods have been replaced with `protocol.handle`"
+    breaking-changes-header: deprecated-protocolunregisterinterceptbufferstringstreamfilehttpprotocol-and-protocolisprotocolregisteredintercepted
+```
+-->
+
 * `scheme` string
 * `handler` Function
  * `request` [ProtocolRequest](structures/protocol-request.md)
@ -250,6 +277,15 @@ property.

 ### `protocol.registerHttpProtocol(scheme, handler)` _Deprecated_

+<!--
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/36674
+    description: "`protocol.register*Protocol` and `protocol.intercept*Protocol` methods have been replaced with `protocol.handle`"
+    breaking-changes-header: deprecated-protocolunregisterinterceptbufferstringstreamfilehttpprotocol-and-protocolisprotocolregisteredintercepted
+```
+-->
+
 * `scheme` string
 * `handler` Function
  * `request` [ProtocolRequest](structures/protocol-request.md)
@ -265,6 +301,15 @@ should be called with an object that has the `url` property.

 ### `protocol.registerStreamProtocol(scheme, handler)` _Deprecated_

+<!--
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/36674
+    description: "`protocol.register*Protocol` and `protocol.intercept*Protocol` methods have been replaced with `protocol.handle`"
+    breaking-changes-header: deprecated-protocolunregisterinterceptbufferstringstreamfilehttpprotocol-and-protocolisprotocolregisteredintercepted
+```
+-->
+
 * `scheme` string
 * `handler` Function
  * `request` [ProtocolRequest](structures/protocol-request.md)
@ -314,6 +359,15 @@ protocol.registerStreamProtocol('atom', (request, callback) => {

 ### `protocol.unregisterProtocol(scheme)` _Deprecated_

+<!--
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/36674
+    description: "`protocol.register*Protocol` and `protocol.intercept*Protocol` methods have been replaced with `protocol.handle`"
+    breaking-changes-header: deprecated-protocolunregisterinterceptbufferstringstreamfilehttpprotocol-and-protocolisprotocolregisteredintercepted
+```
+-->
+
 * `scheme` string

 Returns `boolean` - Whether the protocol was successfully unregistered
@ -322,12 +376,30 @@ Unregisters the custom protocol of `scheme`.

 ### `protocol.isProtocolRegistered(scheme)` _Deprecated_

+<!--
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/36674
+    description: "`protocol.register*Protocol` and `protocol.intercept*Protocol` methods have been replaced with `protocol.handle`"
+    breaking-changes-header: deprecated-protocolunregisterinterceptbufferstringstreamfilehttpprotocol-and-protocolisprotocolregisteredintercepted
+```
+-->
+
 * `scheme` string

 Returns `boolean` - Whether `scheme` is already registered.

 ### `protocol.interceptFileProtocol(scheme, handler)` _Deprecated_

+<!--
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/36674
+    description: "`protocol.register*Protocol` and `protocol.intercept*Protocol` methods have been replaced with `protocol.handle`"
+    breaking-changes-header: deprecated-protocolunregisterinterceptbufferstringstreamfilehttpprotocol-and-protocolisprotocolregisteredintercepted
+```
+-->
+
 * `scheme` string
 * `handler` Function
  * `request` [ProtocolRequest](structures/protocol-request.md)
@ -341,6 +413,15 @@ which sends a file as a response.

 ### `protocol.interceptStringProtocol(scheme, handler)` _Deprecated_

+<!--
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/36674
+    description: "`protocol.register*Protocol` and `protocol.intercept*Protocol` methods have been replaced with `protocol.handle`"
+    breaking-changes-header: deprecated-protocolunregisterinterceptbufferstringstreamfilehttpprotocol-and-protocolisprotocolregisteredintercepted
+```
+-->
+
 * `scheme` string
 * `handler` Function
  * `request` [ProtocolRequest](structures/protocol-request.md)
@ -354,6 +435,15 @@ which sends a `string` as a response.

 ### `protocol.interceptBufferProtocol(scheme, handler)` _Deprecated_

+<!--
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/36674
+    description: "`protocol.register*Protocol` and `protocol.intercept*Protocol` methods have been replaced with `protocol.handle`"
+    breaking-changes-header: deprecated-protocolunregisterinterceptbufferstringstreamfilehttpprotocol-and-protocolisprotocolregisteredintercepted
+```
+-->
+
 * `scheme` string
 * `handler` Function
  * `request` [ProtocolRequest](structures/protocol-request.md)
@ -367,6 +457,15 @@ which sends a `Buffer` as a response.

 ### `protocol.interceptHttpProtocol(scheme, handler)` _Deprecated_

+<!--
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/36674
+    description: "`protocol.register*Protocol` and `protocol.intercept*Protocol` methods have been replaced with `protocol.handle`"
+    breaking-changes-header: deprecated-protocolunregisterinterceptbufferstringstreamfilehttpprotocol-and-protocolisprotocolregisteredintercepted
+```
+-->
+
 * `scheme` string
 * `handler` Function
  * `request` [ProtocolRequest](structures/protocol-request.md)
@ -380,6 +479,15 @@ which sends a new HTTP request as a response.

 ### `protocol.interceptStreamProtocol(scheme, handler)` _Deprecated_

+<!--
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/36674
+    description: "`protocol.register*Protocol` and `protocol.intercept*Protocol` methods have been replaced with `protocol.handle`"
+    breaking-changes-header: deprecated-protocolunregisterinterceptbufferstringstreamfilehttpprotocol-and-protocolisprotocolregisteredintercepted
+```
+-->
+
 * `scheme` string
 * `handler` Function
  * `request` [ProtocolRequest](structures/protocol-request.md)
@ -393,6 +501,15 @@ protocol handler.

 ### `protocol.uninterceptProtocol(scheme)` _Deprecated_

+<!--
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/36674
+    description: "`protocol.register*Protocol` and `protocol.intercept*Protocol` methods have been replaced with `protocol.handle`"
+    breaking-changes-header: deprecated-protocolunregisterinterceptbufferstringstreamfilehttpprotocol-and-protocolisprotocolregisteredintercepted
+```
+-->
+
 * `scheme` string

 Returns `boolean` - Whether the protocol was successfully unintercepted
@ -401,6 +518,15 @@ Remove the interceptor installed for `scheme` and restore its original handler.

 ### `protocol.isProtocolIntercepted(scheme)` _Deprecated_

+<!--
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/36674
+    description: "`protocol.register*Protocol` and `protocol.intercept*Protocol` methods have been replaced with `protocol.handle`"
+    breaking-changes-header: deprecated-protocolunregisterinterceptbufferstringstreamfilehttpprotocol-and-protocolisprotocolregisteredintercepted
+```
+-->
+
 * `scheme` string

 Returns `boolean` - Whether `scheme` is already intercepted.
--- a/docs/api/web-contents.md
+++ b/docs/api/web-contents.md
@ -1126,18 +1126,42 @@ Reloads current page and ignores cache.

 #### `contents.canGoBack()` _Deprecated_

+<!--
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/41752
+    breaking-changes-header: deprecated-clearhistory-cangoback-goback-cangoforward-goforward-gotoindex-cangotooffset-gotooffset-on-webcontents
+```
+-->
+
 Returns `boolean` - Whether the browser can go back to previous web page.

 **Deprecated:** Should use the new [`contents.navigationHistory.canGoBack`](navigation-history.md#navigationhistorycangoback) API.

 #### `contents.canGoForward()` _Deprecated_

+<!--
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/41752
+    breaking-changes-header: deprecated-clearhistory-cangoback-goback-cangoforward-goforward-gotoindex-cangotooffset-gotooffset-on-webcontents
+```
+-->
+
 Returns `boolean` - Whether the browser can go forward to next web page.

 **Deprecated:** Should use the new [`contents.navigationHistory.canGoForward`](navigation-history.md#navigationhistorycangoforward) API.

 #### `contents.canGoToOffset(offset)` _Deprecated_

+<!--
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/41752
+    breaking-changes-header: deprecated-clearhistory-cangoback-goback-cangoforward-goforward-gotoindex-cangotooffset-gotooffset-on-webcontents
+```
+-->
+
 * `offset` Integer

 Returns `boolean` - Whether the web page can go to `offset`.
@ -1146,24 +1170,56 @@ Returns `boolean` - Whether the web page can go to `offset`.

 #### `contents.clearHistory()` _Deprecated_

+<!--
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/41752
+    breaking-changes-header: deprecated-clearhistory-cangoback-goback-cangoforward-goforward-gotoindex-cangotooffset-gotooffset-on-webcontents
+```
+-->
+
 Clears the navigation history.

 **Deprecated:** Should use the new [`contents.navigationHistory.clear`](navigation-history.md#navigationhistoryclear) API.

 #### `contents.goBack()` _Deprecated_

+<!--
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/41752
+    breaking-changes-header: deprecated-clearhistory-cangoback-goback-cangoforward-goforward-gotoindex-cangotooffset-gotooffset-on-webcontents
+```
+-->
+
 Makes the browser go back a web page.

 **Deprecated:** Should use the new [`contents.navigationHistory.goBack`](navigation-history.md#navigationhistorygoback) API.

 #### `contents.goForward()` _Deprecated_

+<!--
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/41752
+    breaking-changes-header: deprecated-clearhistory-cangoback-goback-cangoforward-goforward-gotoindex-cangotooffset-gotooffset-on-webcontents
+```
+-->
+
 Makes the browser go forward a web page.

 **Deprecated:** Should use the new [`contents.navigationHistory.goForward`](navigation-history.md#navigationhistorygoforward) API.

 #### `contents.goToIndex(index)` _Deprecated_

+<!--
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/41752
+    breaking-changes-header: deprecated-clearhistory-cangoback-goback-cangoforward-goforward-gotoindex-cangotooffset-gotooffset-on-webcontents
+```
+-->
+
 * `index` Integer

 Navigates browser to the specified absolute web page index.
@ -1172,6 +1228,14 @@ Navigates browser to the specified absolute web page index.

 #### `contents.goToOffset(offset)` _Deprecated_

+<!--
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/41752
+    breaking-changes-header: deprecated-clearhistory-cangoback-goback-cangoforward-goforward-gotoindex-cangotooffset-gotooffset-on-webcontents
+```
+-->
+
 * `offset` Integer

 Navigates to the specified offset from the "current entry".
@ -2148,6 +2212,15 @@ when the page becomes backgrounded. This also affects the Page Visibility API.

 #### `contents.setBackgroundThrottling(allowed)`

+<!--
+```YAML history
+changes:
+  - pr-url: https://github.com/electron/electron/pull/38924
+    description: "`WebContents.backgroundThrottling` set to false affects all `WebContents` in the host `BrowserWindow`"
+    breaking-changes-header: behavior-changed-webcontentsbackgroundthrottling-set-to-false-affects-all-webcontents-in-the-host-browserwindow
+```
+-->
+
 * `allowed` boolean

 Controls whether or not this WebContents will throttle animations and timers
@ -2258,6 +2331,15 @@ A [`Debugger`](debugger.md) instance for this webContents.

 #### `contents.backgroundThrottling`

+<!--
+```YAML history
+changes:
+  - pr-url: https://github.com/electron/electron/pull/38924
+    description: "`WebContents.backgroundThrottling` set to false affects all `WebContents` in the host `BrowserWindow`"
+    breaking-changes-header: behavior-changed-webcontentsbackgroundthrottling-set-to-false-affects-all-webcontents-in-the-host-browserwindow
+```
+-->
+
 A `boolean` property that determines whether or not this WebContents will throttle animations and timers
 when the page becomes backgrounded. This also affects the Page Visibility API.