refactor: move extension APIs to session.extensions (#45597)
refactor: move extensions to session.extensions
This commit is contained in:
Sam Maddock
GitHub
parent
a63f6143ea
commit
e3f61b465d
14 changed files with 508 additions and 205 deletions
124
docs/api/extensions-api.md
Normal file
124
docs/api/extensions-api.md
Normal file
|
|
@ -0,0 +1,124 @@
|
|||
## Class: Extensions
|
||||
|
||||
> Load and interact with extensions.
|
||||
|
||||
Process: [Main](../glossary.md#main-process)<br />
|
||||
_This class is not exported from the `'electron'` module. It is only available as a return value of other methods in the Electron API._
|
||||
|
||||
Instances of the `Extensions` class are accessed by using `extensions` property of
|
||||
a `Session`.
|
||||
|
||||
### Instance Events
|
||||
|
||||
The following events are available on instances of `Extensions`:
|
||||
|
||||
#### Event: 'extension-loaded'
|
||||
|
||||
Returns:
|
||||
|
||||
* `event` Event
|
||||
* `extension` [Extension](structures/extension.md)
|
||||
|
||||
Emitted after an extension is loaded. This occurs whenever an extension is
|
||||
added to the "enabled" set of extensions. This includes:
|
||||
|
||||
* Extensions being loaded from `Extensions.loadExtension`.
|
||||
* Extensions being reloaded:
|
||||
* from a crash.
|
||||
* if the extension requested it ([`chrome.runtime.reload()`](https://developer.chrome.com/extensions/runtime#method-reload)).
|
||||
|
||||
#### Event: 'extension-unloaded'
|
||||
|
||||
Returns:
|
||||
|
||||
* `event` Event
|
||||
* `extension` [Extension](structures/extension.md)
|
||||
|
||||
Emitted after an extension is unloaded. This occurs when
|
||||
`Session.removeExtension` is called.
|
||||
|
||||
#### Event: 'extension-ready'
|
||||
|
||||
Returns:
|
||||
|
||||
* `event` Event
|
||||
* `extension` [Extension](structures/extension.md)
|
||||
|
||||
Emitted after an extension is loaded and all necessary browser state is
|
||||
initialized to support the start of the extension's background page.
|
||||
|
||||
### Instance Methods
|
||||
|
||||
The following methods are available on instances of `Extensions`:
|
||||
|
||||
#### `extensions.loadExtension(path[, options])`
|
||||
|
||||
* `path` string - Path to a directory containing an unpacked Chrome extension
|
||||
* `options` Object (optional)
|
||||
* `allowFileAccess` boolean - Whether to allow the extension to read local files over `file://`
|
||||
protocol and inject content scripts into `file://` pages. This is required e.g. for loading
|
||||
devtools extensions on `file://` URLs. Defaults to false.
|
||||
|
||||
Returns `Promise<Extension>` - resolves when the extension is loaded.
|
||||
|
||||
This method will raise an exception if the extension could not be loaded. If
|
||||
there are warnings when installing the extension (e.g. if the extension
|
||||
requests an API that Electron does not support) then they will be logged to the
|
||||
console.
|
||||
|
||||
Note that Electron does not support the full range of Chrome extensions APIs.
|
||||
See [Supported Extensions APIs](extensions.md#supported-extensions-apis) for
|
||||
more details on what is supported.
|
||||
|
||||
Note that in previous versions of Electron, extensions that were loaded would
|
||||
be remembered for future runs of the application. This is no longer the case:
|
||||
`loadExtension` must be called on every boot of your app if you want the
|
||||
extension to be loaded.
|
||||
|
||||
```js
|
||||
const { app, session } = require('electron')
|
||||
const path = require('node:path')
|
||||
|
||||
app.whenReady().then(async () => {
|
||||
await session.defaultSession.extensions.loadExtension(
|
||||
path.join(__dirname, 'react-devtools'),
|
||||
// allowFileAccess is required to load the devtools extension on file:// URLs.
|
||||
{ allowFileAccess: true }
|
||||
)
|
||||
// Note that in order to use the React DevTools extension, you'll need to
|
||||
// download and unzip a copy of the extension.
|
||||
})
|
||||
```
|
||||
|
||||
This API does not support loading packed (.crx) extensions.
|
||||
|
||||
**Note:** This API cannot be called before the `ready` event of the `app` module
|
||||
is emitted.
|
||||
|
||||
**Note:** Loading extensions into in-memory (non-persistent) sessions is not
|
||||
supported and will throw an error.
|
||||
|
||||
#### `extensions.removeExtension(extensionId)`
|
||||
|
||||
* `extensionId` string - ID of extension to remove
|
||||
|
||||
Unloads an extension.
|
||||
|
||||
**Note:** This API cannot be called before the `ready` event of the `app` module
|
||||
is emitted.
|
||||
|
||||
#### `extensions.getExtension(extensionId)`
|
||||
|
||||
* `extensionId` string - ID of extension to query
|
||||
|
||||
Returns `Extension | null` - The loaded extension with the given ID.
|
||||
|
||||
**Note:** This API cannot be called before the `ready` event of the `app` module
|
||||
is emitted.
|
||||
|
||||
#### `extensions.getAllExtensions()`
|
||||
|
||||
Returns `Extension[]` - A list of all loaded extensions.
|
||||
|
||||
**Note:** This API cannot be called before the `ready` event of the `app` module
|
||||
is emitted.
|
||||
|
|
@ -14,7 +14,7 @@ but it also happens to support some other extension capabilities.
|
|||
|
||||
Electron only supports loading unpacked extensions (i.e., `.crx` files do not
|
||||
work). Extensions are installed per-`session`. To load an extension, call
|
||||
[`ses.loadExtension`](session.md#sesloadextensionpath-options):
|
||||
[`ses.extensions.loadExtension`](extensions-api.md#extensionsloadextensionpath-options):
|
||||
|
||||
```js
|
||||
const { session } = require('electron')
|
||||
|
|
|
|||
|
|
@ -1485,7 +1485,7 @@ will not work on non-persistent (in-memory) sessions.
|
|||
|
||||
**Note:** On macOS and Windows 10 this word will be removed from the OS custom dictionary as well
|
||||
|
||||
#### `ses.loadExtension(path[, options])`
|
||||
#### `ses.loadExtension(path[, options])` _Deprecated_
|
||||
|
||||
* `path` string - Path to a directory containing an unpacked Chrome extension
|
||||
* `options` Object (optional)
|
||||
|
|
@ -1532,7 +1532,9 @@ is emitted.
|
|||
**Note:** Loading extensions into in-memory (non-persistent) sessions is not
|
||||
supported and will throw an error.
|
||||
|
||||
#### `ses.removeExtension(extensionId)`
|
||||
**Deprecated:** Use the new `ses.extensions.loadExtension` API.
|
||||
|
||||
#### `ses.removeExtension(extensionId)` _Deprecated_
|
||||
|
||||
* `extensionId` string - ID of extension to remove
|
||||
|
||||
|
|
@ -1541,7 +1543,9 @@ Unloads an extension.
|
|||
**Note:** This API cannot be called before the `ready` event of the `app` module
|
||||
is emitted.
|
||||
|
||||
#### `ses.getExtension(extensionId)`
|
||||
**Deprecated:** Use the new `ses.extensions.removeExtension` API.
|
||||
|
||||
#### `ses.getExtension(extensionId)` _Deprecated_
|
||||
|
||||
* `extensionId` string - ID of extension to query
|
||||
|
||||
|
|
@ -1550,13 +1554,17 @@ Returns `Extension | null` - The loaded extension with the given ID.
|
|||
**Note:** This API cannot be called before the `ready` event of the `app` module
|
||||
is emitted.
|
||||
|
||||
#### `ses.getAllExtensions()`
|
||||
**Deprecated:** Use the new `ses.extensions.getExtension` API.
|
||||
|
||||
#### `ses.getAllExtensions()` _Deprecated_
|
||||
|
||||
Returns `Extension[]` - A list of all loaded extensions.
|
||||
|
||||
**Note:** This API cannot be called before the `ready` event of the `app` module
|
||||
is emitted.
|
||||
|
||||
**Deprecated:** Use the new `ses.extensions.getAllExtensions` API.
|
||||
|
||||
#### `ses.getStoragePath()`
|
||||
|
||||
Returns `string | null` - The absolute file system path where data for this
|
||||
|
|
@ -1619,6 +1627,10 @@ session is persisted on disk. For in memory sessions this returns `null`.
|
|||
|
||||
A [`Cookies`](cookies.md) object for this session.
|
||||
|
||||
#### `ses.extensions` _Readonly_
|
||||
|
||||
A [`Extensions`](extensions-api.md) object for this session.
|
||||
|
||||
#### `ses.serviceWorkers` _Readonly_
|
||||
|
||||
A [`ServiceWorkers`](service-workers.md) object for this session.
|
||||
|
|
|
|||
|
|
@ -14,6 +14,13 @@ This document uses the following convention to categorize breaking changes:
|
|||
|
||||
## Planned Breaking API Changes (36.0)
|
||||
|
||||
### Deprecated: Extension methods and events on `session`
|
||||
|
||||
`session.loadExtension`, `session.removeExtension`, `session.getExtension`,
|
||||
`session.getAllExtensions`, 'extension-loaded' event, 'extension-unloaded'
|
||||
event, and 'extension-ready' events have all moved to the new
|
||||
`session.extensions` class.
|
||||
|
||||
### Removed: `systemPreferences.isAeroGlassEnabled()`
|
||||
|
||||
The `systemPreferences.isAeroGlassEnabled()` function has been removed without replacement.
|
||||
|
|
|
|||
|
|
@ -96,9 +96,9 @@ of the extension is not working as expected.
|
|||
[devtools-extension]: https://developer.chrome.com/extensions/devtools
|
||||
[session]: ../api/session.md
|
||||
[react-devtools]: https://chrome.google.com/webstore/detail/react-developer-tools/fmkadmapgofadopljbjfkapdkoienihi
|
||||
[load-extension]: ../api/session.md#sesloadextensionpath-options
|
||||
[load-extension]: ../api/extensions-api.md#extensionsloadextensionpath-options
|
||||
[extension-structure]: ../api/structures/extension.md
|
||||
[remove-extension]: ../api/session.md#sesremoveextensionextensionid
|
||||
[remove-extension]: ../api/extensions-api.md#extensionsremoveextensionextensionid
|
||||
[electron-devtools-installer]: https://github.com/MarshallOfSound/electron-devtools-installer
|
||||
[supported-extension-apis]: ../api/extensions.md
|
||||
[issue-tracker]: https://github.com/electron/electron/issues
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue