Browse Source

docs: update Node API renderer example to use contextBridge (#28371)

Will Anderson 4 years ago
parent
commit
d4eed90145
3 changed files with 21 additions and 15 deletions
  1. 1 1
      docs/api/browser-window.md
  2. 20 1
      docs/api/context-bridge.md
  3. 0 13
      docs/api/process.md

+ 1 - 1
docs/api/browser-window.md

@@ -265,7 +265,7 @@ It creates a new `BrowserWindow` with native properties as set by the `options`.
       be the absolute file path to the script.
       When node integration is turned off, the preload script can reintroduce
       Node global symbols back to the global scope. See example
-      [here](process.md#event-loaded).
+      [here](context-bridge.md#exposing-node-global-symbols).
     * `sandbox` Boolean (optional) - If set, this will sandbox the renderer
       associated with the window, making it compatible with the Chromium
       OS-level sandbox and disabling the Node.js engine. This is not the same as

+ 20 - 1
docs/api/context-bridge.md

@@ -33,7 +33,7 @@ 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
+When `contextIsolation` is enabled in your `webPreferences` (this is the default behavior since Electron 12.0.0), 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.
 
@@ -109,3 +109,22 @@ has been included below for completeness:
 | `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.
+
+### Exposing Node Global Symbols
+
+The `contextBridge` can be used by the preload script to give your renderer access to Node APIs.
+The table of supported types described above also applies to Node APIs that you expose through `contextBridge`.
+Please note that many Node APIs grant access to local system resources.
+Be very cautious about which globals and APIs you expose to untrusted remote content.
+
+```javascript
+const { contextBridge } = require('electron')
+const crypto = require('crypto')
+contextBridge.exposeInMainWorld('nodeCrypto', {
+  sha256sum (data) {
+    const hash = crypto.createHash('sha256')
+    hash.update(data)
+    return hash.digest('hex')
+  }
+})
+```

+ 0 - 13
docs/api/process.md

@@ -42,19 +42,6 @@ In sandboxed renderers the `process` object contains only a subset of the APIs:
 Emitted when Electron has loaded its internal initialization script and is
 beginning to load the web page or the main script.
 
-It can be used by the preload script to add removed Node global symbols back to
-the global scope when node integration is turned off:
-
-```javascript
-// preload.js
-const _setImmediate = setImmediate
-const _clearImmediate = clearImmediate
-process.once('loaded', () => {
-  global.setImmediate = _setImmediate
-  global.clearImmediate = _clearImmediate
-})
-```
-
 ## Properties
 
 ### `process.defaultApp` _Readonly_