docs: update contextIsolation documentation on access to globals (#19732)

This commit is contained in:
Shiranka Miskin 2020-11-18 01:24:00 -05:00 committed by GitHub
parent cc136f2acd
commit ec85a91472
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 13 additions and 14 deletions

View file

@ -337,18 +337,17 @@ It creates a new `BrowserWindow` with native properties as set by the `options`.
more details. more details.
* `contextIsolation` Boolean (optional) - Whether to run Electron APIs and * `contextIsolation` Boolean (optional) - Whether to run Electron APIs and
the specified `preload` script in a separate JavaScript context. Defaults the specified `preload` script in a separate JavaScript context. Defaults
to `false`. The context that the `preload` script runs in will still to `false`. The context that the `preload` script runs in will only have
have full access to the `document` and `window` globals but it will use access to its own dedicated `document` and `window` globals, as well as
its own set of JavaScript builtins (`Array`, `Object`, `JSON`, etc.) its own set of JavaScript builtins (`Array`, `Object`, `JSON`, etc.),
and will be isolated from any changes made to the global environment which are all invisible to the loaded content. The Electron API will only
by the loaded page. The Electron API will only be available in the be available in the `preload` script and not the loaded page. This option
`preload` script and not the loaded page. This option should be used when should be used when loading potentially untrusted remote content to ensure
loading potentially untrusted remote content to ensure the loaded content the loaded content cannot tamper with the `preload` script and any
cannot tamper with the `preload` script and any Electron APIs being used. Electron APIs being used. This option uses the same technique used by
This option uses the same technique used by [Chrome Content Scripts][chrome-content-scripts]. [Chrome Content Scripts][chrome-content-scripts]. You can access this
You can access this context in the dev tools by selecting the context in the dev tools by selecting the 'Electron Isolated Context'
'Electron Isolated Context' entry in the combo box at the top of the entry in the combo box at the top of the Console tab.
Console tab.
* `worldSafeExecuteJavaScript` Boolean (optional) - If true, values returned from `webFrame.executeJavaScript` will be sanitized to ensure JS values * `worldSafeExecuteJavaScript` Boolean (optional) - If true, values returned from `webFrame.executeJavaScript` will be sanitized to ensure JS values
can't unsafely cross between worlds when using `contextIsolation`. The default can't unsafely cross between worlds when using `contextIsolation`. The default
is `false`. In Electron 12, the default will be changed to `true`. _Deprecated_ is `false`. In Electron 12, the default will be changed to `true`. _Deprecated_

View file

@ -233,8 +233,8 @@ practice, that means that global objects like `Array.prototype.push` or
Electron uses the same technology as Chromium's [Content Scripts](https://developer.chrome.com/extensions/content_scripts#execution-environment) Electron uses the same technology as Chromium's [Content Scripts](https://developer.chrome.com/extensions/content_scripts#execution-environment)
to enable this behavior. to enable this behavior.
Even when you use `nodeIntegration: false` to enforce strong isolation and Even when `nodeIntegration: false` is used, to truly enforce strong isolation
prevent the use of Node primitives, `contextIsolation` must also be used. and prevent the use of Node primitives `contextIsolation` **must** also be used.
### Why & How? ### Why & How?