зеркало из https://github.com/electron/electron.git
Keeley Hammond
GitHub
Родитель
2471ebf39c
Коммит
9e421e8f43
|
|
@ -0,0 +1,47 @@
|
|||
{
|
||||
"title": "JSON schema for API history blocks in Electron documentation",
|
||||
"$schema": "http://json-schema.org/draft-07/schema#",
|
||||
"$comment": "If you change this schema, remember to edit the TypeScript interfaces in the linting script.",
|
||||
"definitions": {
|
||||
"baseChangeSchema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"pr-url": {
|
||||
"description": "URL to the 'main' GitHub Pull Request for the change (i.e. not a backport PR)",
|
||||
"type": "string", "pattern": "^https://github.com/electron/electron/pull/\\d+$",
|
||||
"examples": [ "https://github.com/electron/electron/pull/26789" ]
|
||||
},
|
||||
"breaking-changes-header": {
|
||||
"description": "Heading ID for the change in `electron/docs/breaking-changes.md`",
|
||||
"type": "string", "minLength": 3,
|
||||
"examples": [ "deprecated-browserwindowsettrafficlightpositionposition" ]
|
||||
},
|
||||
"description": {
|
||||
"description": "Short description of the change",
|
||||
"type": "string", "minLength": 3, "maxLength": 120,
|
||||
"examples": [ "Made `trafficLightPosition` option work for `customButtonOnHover`." ]
|
||||
}
|
||||
},
|
||||
"required": [ "pr-url" ],
|
||||
"additionalProperties": false
|
||||
},
|
||||
"addedChangeSchema": {
|
||||
"allOf": [ { "$ref": "#/definitions/baseChangeSchema" } ]
|
||||
},
|
||||
"deprecatedChangeSchema": {
|
||||
"$comment": "TODO: Make 'breaking-changes-header' required in the future.",
|
||||
"allOf": [ { "$ref": "#/definitions/baseChangeSchema" } ]
|
||||
},
|
||||
"changesChangeSchema": {
|
||||
"$comment": "Unlike RFC, added `'type': 'object'` to appease AJV strict mode",
|
||||
"allOf": [ { "$ref": "#/definitions/baseChangeSchema" }, { "type": "object", "required": [ "description" ] } ]
|
||||
}
|
||||
},
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"added": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "$ref": "#/definitions/addedChangeSchema" } },
|
||||
"deprecated": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "$ref": "#/definitions/deprecatedChangeSchema" } },
|
||||
"changes": { "type": "array", "minItems": 1, "items": { "$ref": "#/definitions/changesChangeSchema" } }
|
||||
},
|
||||
"additionalProperties": false
|
||||
}
|
||||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,190 @@
|
|||
# Electron API History Migration Guide
|
||||
|
||||
This document demonstrates how to add API History blocks to existing APIs.
|
||||
|
||||
## API history information
|
||||
|
||||
Here are some resources you can use to find information on the history of an API:
|
||||
|
||||
### Breaking Changes
|
||||
|
||||
* [`breaking-changes.md`](../breaking-changes.md)
|
||||
|
||||
### Additions
|
||||
|
||||
* `git blame`
|
||||
* [Release notes](https://github.com/electron/electron/releases/)
|
||||
* [`electron-api-historian`](https://github.com/electron/electron-api-historian)
|
||||
|
||||
## Example
|
||||
|
||||
> [!NOTE]
|
||||
> The associated API is already removed, we will ignore that for the purpose of
|
||||
> this example.
|
||||
|
||||
If we search through [`breaking-changes.md`](../breaking-changes.md) we can find
|
||||
[a function that was deprecated in Electron `25.0`](../breaking-changes.md#deprecated-browserwindowsettrafficlightpositionposition).
|
||||
|
||||
```markdown
|
||||
<!-- docs/breaking-changes.md -->
|
||||
### Deprecated: `BrowserWindow.getTrafficLightPosition()`
|
||||
|
||||
`BrowserWindow.getTrafficLightPosition()` has been deprecated, the
|
||||
`BrowserWindow.getWindowButtonPosition()` API should be used instead
|
||||
which returns `null` instead of `{ x: 0, y: 0 }` when there is no custom
|
||||
position.
|
||||
|
||||
<!-- docs/api/browser-window.md -->
|
||||
#### `win.getTrafficLightPosition()` _macOS_ _Deprecated_
|
||||
|
||||
Returns `Point` - The custom position for the traffic light buttons in
|
||||
frameless window, `{ x: 0, y: 0 }` will be returned when there is no custom
|
||||
position.
|
||||
```
|
||||
|
||||
We can then use `git blame` to find the Pull Request associated with that entry:
|
||||
|
||||
```bash
|
||||
$ grep -n "BrowserWindow.getTrafficLightPosition" docs/breaking-changes.md
|
||||
523:### Deprecated: `BrowserWindow.getTrafficLightPosition()`
|
||||
525:`BrowserWindow.getTrafficLightPosition()` has been deprecated, the
|
||||
|
||||
$ git blame -L523,524 -- docs/breaking-changes.md
|
||||
1e206deec3e (Keeley Hammond 2023-04-06 21:23:29 -0700 523) ### Deprecated: `BrowserWindow.getTrafficLightPosition()`
|
||||
1e206deec3e (Keeley Hammond 2023-04-06 21:23:29 -0700 524)
|
||||
|
||||
$ git log -1 1e206deec3e
|
||||
commit 1e206deec3ef142460c780307752a84782f9baed (tag: v26.0.0-nightly.20230407)
|
||||
Author: Keeley Hammond <vertedinde@electronjs.org>
|
||||
Date: Thu Apr 6 21:23:29 2023 -0700
|
||||
|
||||
docs: update E24/E25 breaking changes (#37878) <-- This is the associated Pull Request
|
||||
```
|
||||
|
||||
Verify that the Pull Request is correct and make a corresponding entry in the
|
||||
API History:
|
||||
|
||||
> [!NOTE]
|
||||
> Refer to the [API History section of `styleguide.md`](../styleguide.md#api-history)
|
||||
for information on how to create API History blocks.
|
||||
|
||||
`````markdown
|
||||
#### `win.getTrafficLightPosition()` _macOS_ _Deprecated_
|
||||
|
||||
<!--
|
||||
```YAML history
|
||||
deprecated:
|
||||
- pr-url: https://github.com/electron/electron/pull/37878
|
||||
breaking-changes-header: deprecated-browserwindowgettrafficlightposition
|
||||
```
|
||||
-->
|
||||
|
||||
Returns `Point` - The custom position for the traffic light buttons in
|
||||
frameless window, `{ x: 0, y: 0 }` will be returned when there is no custom
|
||||
position.
|
||||
`````
|
||||
|
||||
You can keep looking through `breaking-changes.md` to find other breaking changes
|
||||
and add those in.
|
||||
|
||||
You can also use [`git log -L :<funcname>:<file>`](https://git-scm.com/docs/git-log#Documentation/git-log.txt--Lltfuncnamegtltfilegt):
|
||||
|
||||
```bash
|
||||
$ git log --reverse -L :GetTrafficLightPosition:shell/browser/native_window_mac.mm
|
||||
commit e01b1831d96d5d68f54af879b00c617358df5372
|
||||
Author: Cheng Zhao <zcbenz@gmail.com>
|
||||
Date: Wed Dec 16 14:30:39 2020 +0900
|
||||
|
||||
feat: make trafficLightPosition work for customButtonOnHover (#26789)
|
||||
```
|
||||
|
||||
Verify that the Pull Request is correct and make a corresponding entry in the
|
||||
API History:
|
||||
|
||||
`````markdown
|
||||
#### `win.getTrafficLightPosition()` _macOS_ _Deprecated_
|
||||
|
||||
<!--
|
||||
```YAML history
|
||||
added:
|
||||
- pr-url: https://github.com/electron/electron/pull/22533
|
||||
changes:
|
||||
- pr-url: https://github.com/electron/electron/pull/26789
|
||||
description: "Made `trafficLightPosition` option work for `customButtonOnHover` window."
|
||||
breaking-changes-header: behavior-changed-draggable-regions-on-macos
|
||||
```
|
||||
-->
|
||||
|
||||
Returns `Point` - The custom position for the traffic light buttons in
|
||||
frameless window, `{ x: 0, y: 0 }` will be returned when there is no custom
|
||||
position.
|
||||
`````
|
||||
|
||||
We will then look for when the API was originally added:
|
||||
|
||||
```bash
|
||||
$ git log --reverse -L :GetTrafficLightPosition:shell/browser/native_window_mac.mm
|
||||
commit 3e2cec83d927b991855e21cc311ca9046e332601
|
||||
Author: Samuel Attard <sattard@slack-corp.com>
|
||||
Date: Thu Mar 5 14:22:12 2020 -0800
|
||||
|
||||
feat: programmatically modify traffic light positioning (#22533)
|
||||
```
|
||||
|
||||
Alternatively, you can use `git blame`:
|
||||
|
||||
```bash
|
||||
$ git checkout 1e206deec3e^
|
||||
HEAD is now at e8c87859c4 fix: showAboutPanel also on linux (#37828)
|
||||
|
||||
$ grep -n "getTrafficLightPosition" docs/api/browser-window.md
|
||||
1867:#### `win.getTrafficLightPosition()` _macOS_ _Deprecated_
|
||||
|
||||
$ git blame -L1867,1868 -- docs/api/browser-window.md
|
||||
0de1012280e (Cheng Zhao 2023-02-17 19:06:32 +0900 1867) #### `win.getTrafficLightPosition()` _macOS_ _Deprecated_
|
||||
3e2cec83d92 (Samuel Attard 2020-03-05 14:22:12 -0800 1868)
|
||||
|
||||
$ git checkout 0de1012280e^
|
||||
HEAD is now at 0a5e634736 test: rename & split internal module tests (#37318)
|
||||
|
||||
$ grep -n "getTrafficLightPosition" docs/api/browser-window.md
|
||||
1851:#### `win.getTrafficLightPosition()` _macOS_
|
||||
|
||||
$ git blame -L1851,1852 -- docs/api/browser-window.md
|
||||
3e2cec83d92 (Samuel Attard 2020-03-05 14:22:12 -0800 1851) #### `win.getTrafficLightPosition()` _macOS_
|
||||
3e2cec83d92 (Samuel Attard 2020-03-05 14:22:12 -0800 1852)
|
||||
|
||||
$ git checkout 3e2cec83d92^
|
||||
HEAD is now at 1811751c6c docs: clean up dark mode related docs (#22489)
|
||||
|
||||
$ grep -n "getTrafficLightPosition" docs/api/browser-window.md
|
||||
(Nothing)
|
||||
|
||||
$ git checkout 3e2cec83d92
|
||||
HEAD is now at 3e2cec83d9 feat: programmatically modify traffic light positioning (#22533)
|
||||
```
|
||||
|
||||
Verify that the Pull Request is correct and make a corresponding entry in the
|
||||
API History:
|
||||
|
||||
`````markdown
|
||||
#### `win.getTrafficLightPosition()` _macOS_ _Deprecated_
|
||||
|
||||
<!--
|
||||
```YAML history
|
||||
added:
|
||||
- pr-url: https://github.com/electron/electron/pull/22533
|
||||
changes:
|
||||
- pr-url: https://github.com/electron/electron/pull/26789
|
||||
description: "Made `trafficLightPosition` option work for `customButtonOnHover` window."
|
||||
breaking-changes-header: behavior-changed-draggable-regions-on-macos
|
||||
deprecated:
|
||||
- pr-url: https://github.com/electron/electron/pull/37878
|
||||
breaking-changes-header: deprecated-browserwindowgettrafficlightposition
|
||||
```
|
||||
-->
|
||||
|
||||
Returns `Point` - The custom position for the traffic light buttons in
|
||||
frameless window, `{ x: 0, y: 0 }` will be returned when there is no custom
|
||||
position.
|
||||
`````
|
||||
|
|
@ -250,6 +250,157 @@ The properties chapter must be in following form:
|
|||
The heading can be `###` or `####`-levels depending on whether the property
|
||||
belongs to a module or a class.
|
||||
|
||||
## API History
|
||||
|
||||
An "API History" block is a YAML code block encapsulated by an HTML comment that
|
||||
should be placed directly after the Markdown header for a class or method, like so:
|
||||
|
||||
`````markdown
|
||||
#### `win.setTrafficLightPosition(position)` _macOS_
|
||||
|
||||
<!--
|
||||
```YAML history
|
||||
added:
|
||||
- pr-url: https://github.com/electron/electron/pull/22533
|
||||
changes:
|
||||
- pr-url: https://github.com/electron/electron/pull/26789
|
||||
description: "Made `trafficLightPosition` option work for `customButtonOnHover` window."
|
||||
deprecated:
|
||||
- pr-url: https://github.com/electron/electron/pull/37094
|
||||
breaking-changes-header: deprecated-browserwindowsettrafficlightpositionposition
|
||||
```
|
||||
-->
|
||||
|
||||
* `position` [Point](structures/point.md)
|
||||
|
||||
Set a custom position for the traffic light buttons. Can only be used with `titleBarStyle` set to `hidden`.
|
||||
`````
|
||||
|
||||
It should adhere to the API History [JSON Schema](https://json-schema.org/)
|
||||
(`api-history.schema.json`) which you can find in the `docs` folder.
|
||||
The [API History Schema RFC][api-history-schema-rfc] includes example usage and detailed
|
||||
explanations for each aspect of the schema.
|
||||
|
||||
The purpose of the API History block is to describe when/where/how/why an API was:
|
||||
|
||||
* Added
|
||||
* Changed (usually breaking changes)
|
||||
* Deprecated
|
||||
|
||||
Each API change listed in the block should include a link to the
|
||||
PR where that change was made along with an optional short description of the
|
||||
change. If applicable, include the [heading id](https://gist.github.com/asabaylus/3071099)
|
||||
for that change from the [breaking changes documentation](./breaking-changes.md).
|
||||
|
||||
The [API History linting script][api-history-linting-script] (`lint:api-history`)
|
||||
validates API History blocks in the Electron documentation against the schema and
|
||||
performs some other checks. You can look at its [tests][api-history-tests] for more
|
||||
details.
|
||||
|
||||
There are a few style guidelines that aren't covered by the linting script:
|
||||
|
||||
### Format
|
||||
|
||||
Always adhere to this format:
|
||||
|
||||
```markdown
|
||||
API HEADER | #### `win.flashFrame(flag)`
|
||||
BLANK LINE |
|
||||
HTML COMMENT OPENING TAG | <!--
|
||||
API HISTORY OPENING TAG | ```YAML history
|
||||
API HISTORY | added:
|
||||
| - pr-url: https://github.com/electron/electron/pull/22533
|
||||
API HISTORY CLOSING TAG | ```
|
||||
HTML COMMENT CLOSING TAG | -->
|
||||
BLANK LINE |
|
||||
```
|
||||
|
||||
### YAML
|
||||
|
||||
* Use two spaces for indentation.
|
||||
* Do not use comments.
|
||||
|
||||
### Descriptions
|
||||
|
||||
* Always wrap descriptions with double quotation marks (i.e. "example").
|
||||
* [Certain special characters (e.g. `[`, `]`) can break YAML parsing](https:/stackoverflow.com/a/37015689/19020549).
|
||||
* Describe the change in a way relevant to app developers and make it
|
||||
capitalized, punctuated, and past tense.
|
||||
* Refer to [Clerk](https://github.com/electron/clerk/blob/main/README.md#examples)
|
||||
for examples.
|
||||
* Keep descriptions concise.
|
||||
* Ideally, a description will match its corresponding header in the
|
||||
breaking changes document.
|
||||
* Favor using the release notes from the associated PR whenever possible.
|
||||
* Developers can always view the breaking changes document or linked
|
||||
pull request for more details.
|
||||
|
||||
### Placement
|
||||
|
||||
Generally, you should place the API History block directly after the Markdown header
|
||||
for a class or method that was changed. However, there are some instances where this
|
||||
is ambiguous:
|
||||
|
||||
#### Chromium bump
|
||||
|
||||
* [chore: bump chromium to 122.0.6194.0 (main)](https://github.com/electron/electron/pull/40750)
|
||||
* [Behavior Changed: cross-origin iframes now use Permission Policy to access features][api-history-cross-origin]
|
||||
|
||||
Sometimes a breaking change doesn't relate to any of the existing APIs. In this
|
||||
case, it is ok not to add API History anywhere.
|
||||
|
||||
#### Change affecting multiple APIs
|
||||
|
||||
* [refactor: ensure IpcRenderer is not bridgable](https://github.com/electron/electron/pull/40330)
|
||||
* [Behavior Changed: ipcRenderer can no longer be sent over the contextBridge][api-history-ipc-renderer]
|
||||
|
||||
Sometimes a breaking change involves multiple APIs. In this case, place the
|
||||
API History block under the top-level Markdown header for each of the
|
||||
involved APIs.
|
||||
|
||||
`````markdown
|
||||
# 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
|
||||
`````
|
||||
|
||||
`````markdown
|
||||
# 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
|
||||
```
|
||||
-->
|
||||
|
||||
Process: [Renderer](../glossary.md#renderer-process)
|
||||
`````
|
||||
|
||||
Notice how an API History block wasn't added under:
|
||||
|
||||
* `contextBridge.exposeInMainWorld(apiKey, api)`
|
||||
|
||||
since that function wasn't changed, only how it may be used:
|
||||
|
||||
```patch
|
||||
contextBridge.exposeInMainWorld('app', {
|
||||
- ipcRenderer,
|
||||
+ onEvent: (cb) => ipcRenderer.on('foo', (e, ...args) => cb(args))
|
||||
})
|
||||
```
|
||||
|
||||
## Documentation translations
|
||||
|
||||
See [electron/i18n](https://github.com/electron/i18n#readme)
|
||||
|
|
@ -257,3 +408,8 @@ See [electron/i18n](https://github.com/electron/i18n#readme)
|
|||
[title-case]: https://apastyle.apa.org/style-grammar-guidelines/capitalization/title-case
|
||||
[sentence-case]: https://apastyle.apa.org/style-grammar-guidelines/capitalization/sentence-case
|
||||
[markdownlint]: https://github.com/DavidAnson/markdownlint
|
||||
[api-history-schema-rfc]: https://github.com/electron/rfcs/blob/f36e0a8483e1ea844710890a8a7a1bd58ecbac05/text/0004-api-history-schema.md
|
||||
[api-history-linting-script]: https://github.com/electron/lint-roller/blob/3030970136ec6b41028ef973f944d3e5cad68e1c/bin/lint-markdown-api-history.ts
|
||||
[api-history-tests]: https://github.com/electron/lint-roller/blob/main/tests/lint-roller-markdown-api-history.spec.ts
|
||||
[api-history-cross-origin]: https://github.com/electron/electron/blob/f508f6b6b570481a2b61d8c4f8c1951f492e4309/docs/breaking-changes.md#behavior-changed-cross-origin-iframes-now-use-permission-policy-to-access-features
|
||||
[api-history-ipc-renderer]: https://github.com/electron/electron/blob/f508f6b6b570481a2b61d8c4f8c1951f492e4309/docs/breaking-changes.md#behavior-changed-ipcrenderer-can-no-longer-be-sent-over-the-contextbridge
|
||||
|
|
|
|||
|
|
@ -86,12 +86,13 @@
|
|||
"lint:objc": "node ./script/lint.js --objc",
|
||||
"lint:py": "node ./script/lint.js --py",
|
||||
"lint:gn": "node ./script/lint.js --gn",
|
||||
"lint:docs": "remark docs -qf && npm run lint:js-in-markdown && npm run create-typescript-definitions && npm run lint:ts-check-js-in-markdown && npm run lint:docs-fiddles && npm run lint:docs-relative-links && npm run lint:markdown",
|
||||
"lint:docs": "remark docs -qf && npm run lint:js-in-markdown && npm run create-typescript-definitions && npm run lint:ts-check-js-in-markdown && npm run lint:docs-fiddles && npm run lint:docs-relative-links && npm run lint:markdown && npm run lint:api-history",
|
||||
"lint:docs-fiddles": "standard \"docs/fiddles/**/*.js\"",
|
||||
"lint:docs-relative-links": "lint-roller-markdown-links --root docs \"**/*.md\"",
|
||||
"lint:markdown": "node ./script/lint.js --md",
|
||||
"lint:ts-check-js-in-markdown": "lint-roller-markdown-ts-check --root docs \"**/*.md\" --ignore \"breaking-changes.md\"",
|
||||
"lint:js-in-markdown": "lint-roller-markdown-standard --root docs \"**/*.md\"",
|
||||
"lint:api-history": "lint-roller-markdown-api-history --root \"./docs/api/\" --schema \"./docs/api-history.schema.json\" --breaking-changes-file \"./docs/breaking-changes.md\" --check-placement --check-strings \"*.md\"",
|
||||
"create-api-json": "node script/create-api-json.js",
|
||||
"create-typescript-definitions": "npm run create-api-json && electron-typescript-definitions --api=electron-api.json && node spec/ts-smoke/runner.js",
|
||||
"gn-typescript-definitions": "npm run create-typescript-definitions && shx cp electron.d.ts",
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче