electron/docs/api/breaking-changes.md

284 lines
5.5 KiB
Markdown
Raw Normal View History

# API Contract
Breaking changes will be included in this documentation, and deprecation warnings added to JS code where possible, at least [one major version](electron-versioning.md#semver) before the change is made.
# `FIXME` comments
The `FIXME` string is used in code comments to denote things that should be fixed for future releases. See https://github.com/electron/electron/search?q=fixme
# Planned Breaking API Changes (4.0)
The following list includes the APIs that will be removed in Electron 4.0.
There is no timetable for when this release will occur but deprecation
warnings will be added at least [one major version](electron-versioning.md#semver) beforehand.
## `app.makeSingleInstance`
```js
// Deprecated
app.makeSingleInstance(function (argv, cwd) {
})
// Replace with
app.requestSingleInstanceLock()
app.on('second-instance', function (argv, cwd) {
})
```
## `app.releaseSingleInstance`
```js
// Deprecated
app.releaseSingleInstance()
// Replace with
app.releaseSingleInstanceLock()
```
# Planned Breaking API Changes (3.0)
2016-09-07 18:41:54 +00:00
The following list includes the APIs that will be removed in Electron 3.0.
2016-09-07 18:41:54 +00:00
2017-05-18 03:01:06 +00:00
## `app`
```js
// Deprecated
app.getAppMemoryInfo()
// Replace with
app.getAppMetrics()
```
2016-09-08 16:09:49 +00:00
## `BrowserWindow`
```js
// Deprecated
2016-09-08 16:15:05 +00:00
let optionsA = {webPreferences: {blinkFeatures: ''}}
let windowA = new BrowserWindow(optionsA)
2016-09-08 16:09:49 +00:00
// Replace with
2016-09-08 16:15:05 +00:00
let optionsB = {webPreferences: {enableBlinkFeatures: ''}}
let windowB = new BrowserWindow(optionsB)
// Deprecated
window.on('app-command', (e, cmd) => {
if (cmd === 'media-play_pause') {
// do something
}
})
// Replace with
window.on('app-command', (e, cmd) => {
if (cmd === 'media-play-pause') {
// do something
}
})
2016-09-08 16:09:49 +00:00
```
## `clipboard`
2016-09-07 18:41:54 +00:00
```js
// Deprecated
clipboard.readRtf()
// Replace with
clipboard.readRTF()
// Deprecated
clipboard.writeRtf()
// Replace with
clipboard.writeRTF()
// Deprecated
clipboard.readHtml()
// Replace with
clipboard.readHTML()
// Deprecated
clipboard.writeHtml()
// Replace with
clipboard.writeHTML()
2016-09-08 16:09:49 +00:00
```
2016-11-28 23:06:03 +00:00
## `crashReporter`
```js
// Deprecated
crashReporter.start({
companyName: 'Crashly',
submitURL: 'https://crash.server.com',
autoSubmit: true
})
// Replace with
crashReporter.start({
companyName: 'Crashly',
submitURL: 'https://crash.server.com',
uploadToServer: true
})
```
2016-09-08 16:09:49 +00:00
## `nativeImage`
2016-09-07 18:41:54 +00:00
2016-09-08 16:09:49 +00:00
```js
// Deprecated
nativeImage.createFromBuffer(buffer, 1.0)
// Replace with
nativeImage.createFromBuffer(buffer, {
scaleFactor: 1.0
})
2016-09-08 16:09:49 +00:00
```
2016-09-07 18:41:54 +00:00
## `screen`
2016-09-16 22:57:07 +00:00
```js
// Deprecated
screen.getMenuBarHeight()
2016-09-16 22:57:07 +00:00
// Replace with
screen.getPrimaryDisplay().workArea
2016-09-16 22:57:07 +00:00
```
2017-02-07 23:44:56 +00:00
## `session`
```js
// Deprecated
ses.setCertificateVerifyProc(function (hostname, certificate, callback) {
callback(true)
})
// Replace with
2017-02-08 00:35:37 +00:00
ses.setCertificateVerifyProc(function (request, callback) {
2017-02-07 23:44:56 +00:00
callback(0)
})
```
2016-09-08 16:09:49 +00:00
## `Tray`
2016-09-07 18:41:54 +00:00
2016-09-08 16:09:49 +00:00
```js
2016-09-07 18:41:54 +00:00
// Deprecated
tray.setHighlightMode(true)
// Replace with
tray.setHighlightMode('on')
// Deprecated
tray.setHighlightMode(false)
// Replace with
tray.setHighlightMode('off')
2016-09-08 16:09:49 +00:00
```
2016-09-07 18:41:54 +00:00
2016-09-08 16:09:49 +00:00
## `webContents`
```js
2016-09-07 18:41:54 +00:00
// Deprecated
webContents.openDevTools({detach: true})
// Replace with
webContents.openDevTools({mode: 'detach'})
```
## `webFrame`
```js
2016-11-14 18:33:30 +00:00
// Deprecated
webFrame.registerURLSchemeAsSecure('app')
// Replace with
protocol.registerStandardSchemes(['app'], {secure: true})
2016-11-14 18:33:30 +00:00
// Deprecated
webFrame.registerURLSchemeAsPrivileged('app', {secure: true})
// Replace with
protocol.registerStandardSchemes(['app'], {secure: true})
```
## Node Headers URL
This is the URL specified as `disturl` in a `.npmrc` file or as the `--dist-url`
command line flag when building native Node modules.
Deprecated: https://atom.io/download/atom-shell
Replace with: https://atom.io/download/electron
# Breaking API Changes (2.0)
## `BrowserWindow`
```js
// Deprecated
let optionsA = {titleBarStyle: 'hidden-inset'}
let windowA = new BrowserWindow(optionsA)
// Replace with
let optionsB = {titleBarStyle: 'hiddenInset'}
let windowB = new BrowserWindow(optionsB)
```
## `menu`
```js
// Deprecated
menu.popup(browserWindow, 100, 200, 2)
// Replace with
menu.popup(browserWindow, {x: 100, y: 200, positioningItem: 2})
```
2018-05-29 09:24:39 +00:00
## `nativeImage`
```js
// Deprecated
nativeImage.toPng()
// Replace with
nativeImage.toPNG()
// Deprecated
nativeImage.toJpeg()
// Replace with
nativeImage.toJPEG()
```
## `process`
* `process.versions.electron` and `process.version.chrome` will be made
read-only properties for consistency with the other `process.versions`
properties set by Node.
## `webContents`
```js
// Deprecated
webContents.setZoomLevelLimits(1, 2)
// Replace with
webContents.setVisualZoomLevelLimits(1, 2)
```
## `webFrame`
```js
// Deprecated
webFrame.setZoomLevelLimits(1, 2)
// Replace with
webFrame.setVisualZoomLevelLimits(1, 2)
```
## `<webview>`
```js
// Deprecated
webview.setZoomLevelLimits(1, 2)
// Replace with
webview.setVisualZoomLevelLimits(1, 2)
```
## Duplicate ARM Assets
Each Electron release includes two identical ARM builds with slightly different
filenames, like `electron-v1.7.3-linux-arm.zip` and
`electron-v1.7.3-linux-armv7l.zip`. The asset with the `v7l` prefix was added
to clarify to users which ARM version it supports, and to disambiguate it from
future armv6l and arm64 assets that may be produced.
The file _without the prefix_ is still being published to avoid breaking any
setups that may be consuming it. Starting at 2.0, the un-prefixed file will
no longer be published.
For details, see
[6986](https://github.com/electron/electron/pull/6986)
and
[7189](https://github.com/electron/electron/pull/7189).