Skip to content

Commit

Permalink
docs: clean up context bridge API docs (#21916)
Browse files Browse the repository at this point in the history
  • Loading branch information
trop[bot] authored and codebytere committed Jan 28, 2020
1 parent 0a3a0de commit 1c1e9fc
Showing 1 changed file with 14 additions and 13 deletions.
27 changes: 14 additions & 13 deletions docs/api/context-bridge.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,13 +28,14 @@ window.electron.doThing()

### Main World

The "Main World" is the javascript context that your main renderer code runs in. By default the page you load in your renderer
executes code in this world.
The "Main World" is the JavaScript context that your main renderer code runs in. By default, the
page you load in your renderer executes code in this world.

### Isolated World

When `contextIsolation` is enabled in your `webPreferences` your `preload` scripts run in an "Isolated World". You can read more about
context isolation and what it affects in the [BrowserWindow](browser-window.md) docs.
When `contextIsolation` is enabled in your `webPreferences`, your `preload` scripts run in an
"Isolated World". You can read more about context isolation and what it affects in the
[security](../tutorial/security.md#3-enable-context-isolation-for-remote-content) docs.

## Methods

Expand All @@ -50,12 +51,12 @@ The `contextBridge` module has the following methods:
### API Objects

The `api` object provided to [`exposeInMainWorld`](#contextbridgeexposeinmainworldapikey-api-experimental) must be an object
whose keys are strings and values are a `Function`, `String`, `Number`, `Array`, `Boolean` or another nested object that meets the same conditions.
whose keys are strings and values are a `Function`, `String`, `Number`, `Array`, `Boolean`, or another nested object that meets the same conditions.

`Function` values are proxied to the other context and all other values are **copied** and **frozen**. I.e. Any data / primitives sent in
`Function` values are proxied to the other context and all other values are **copied** and **frozen**. Any data / primitives sent in
the API object become immutable and updates on either side of the bridge do not result in an update on the other side.

An example of a complex API object is shown below.
An example of a complex API object is shown below:

```javascript
const { contextBridge } = require('electron')
Expand Down Expand Up @@ -90,22 +91,22 @@ results in some key limitations that we've outlined below.

#### Parameter / Error / Return Type support

Because parameters, errors and return values are **copied** when they are sent over the bridge there are only certain types that can be used.
At a high level if the type you want to use can be serialized and un-serialized into the same object it will work. A table of type support
has been included below for completeness.
Because parameters, errors and return values are **copied** when they are sent over the bridge, there are only certain types that can be used.
At a high level, if the type you want to use can be serialized and deserialized into the same object it will work. A table of type support
has been included below for completeness:

| Type | Complexity | Parameter Support | Return Value Support | Limitations |
| ---- | ---------- | ----------------- | -------------------- | ----------- |
| `String` | Simple ||| N/A |
| `Number` | Simple ||| N/A |
| `Boolean` | Simple ||| N/A |
| `Object` | Complex ||| Keys must be supported "Simple" types in this table. Values must be supported in this table. Prototype modifications are dropped. Sending custom classes will copy values but not the prototype. |
| `Object` | Complex ||| Keys must be supported using only "Simple" types in this table. Values must be supported in this table. Prototype modifications are dropped. Sending custom classes will copy values but not the prototype. |
| `Array` | Complex ||| Same limitations as the `Object` type |
| `Error` | Complex ||| Errors that are thrown are also copied, this can result in the message and stack trace of the error changing slightly due to being thrown in a different context |
| `Promise` | Complex ||| Promises are only proxied if they are a the return value or exact parameter. Promises nested in arrays or obejcts will be dropped. |
| `Promise` | Complex ||| Promises are only proxied if they are the return value or exact parameter. Promises nested in arrays or objects will be dropped. |
| `Function` | Complex ||| Prototype modifications are dropped. Sending classes or constructors will not work. |
| [Cloneable Types](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm) | Simple ||| See the linked document on cloneable types |
| `Symbol` | N/A ||| Symbols cannot be copied across contexts so they are dropped |


If the type you care about is not in the above table it is probably not supported.
If the type you care about is not in the above table, it is probably not supported.

0 comments on commit 1c1e9fc

Please sign in to comment.