contextBridge

Crée un pont synchrone sécurisé, bidirectionnel entre des contextes isolés

Processus : Renderer

Exemple d’une API exposée à un rendu à partir d’un script de preload:

// Preload (Isolated World)
const { contextBridge, ipcRenderer } = require('electron')

contextBridge.exposeInMainWorld(
  'electron',
  {
    doThing: () => ipcRenderer.send('do-a-thing')
  }
)

// Renderer (Main World)

window.electron.doThing()

Glossaire

Main World

« Main World » est le contexte JavaScript dans lequel votre code de rendu principal s'exécute. Par défaut, la page que vous chargez dans votre moteur de rendu exécute son code dans cet univers.

Isolated World

Votre script preload s'exécute dans un "Isolated World" lorsque contextIsolation est activé dans vos webPreferences (ce qui est le comportement par défaut depuis Electron 12.0.0). Vous pourrez en savoir plus sur l'isolement du contexte et ce qu'il affecte dans la partie sécurité de la documentation. .

Méthodes

Le module contextBridge possède les méthodes suivantes :

contextBridge.exposeInMainWorld(apiKey, api)

• apiKey string - La clé à utiliser pour injecter l'API dans fenêtre. L’API sera accessible par window[apiKey].
• api any- Votre API, plus d'informations sur ce que peut être cette API et son fonctionnement est disponible ci-dessous.

Utilisation

API

L' api fourni à exposeInMainWorld peut être du type Function, string, number, Array, boolean ou un objet dont les clés sont des chaînes de caractères et les valeurs du type Function, string, number, Array, boolean ou un autre objet imbriqué qui remplit les mêmes conditions.

Function values are proxied to the other context and all other values are copied and frozen. Toutes les données ou primitives envoyées par l'API deviennent immuables et les mises à jour de chaque côté du pont de connexion ne donnent pas lieu à une mise à jour de l'autre côté.

Exemple d’API complexe:

const { contextBridge } = require('electron')

contextBridge.exposeInMainWorld(
  'electron',
  {
    doThing: () => ipcRenderer.send('do-a-thing'),
    myPromises: [Promise.resolve(), Promise.reject(new Error('whoops'))],
    anAsyncFunction: async () => 123,
    data: {
      myFlags: ['a', 'b', 'c'],
      bootTime: 1234
    },
    nestedAPI: {
      evenDeeper: {
        youCanDoThisAsMuchAsYouWant: {
          fn: () => ({
            returnData: 123
          })
        }
      }
    }
  }
)

API Functions

Les valeurs Function que vous liez à travers le contextBridge sont servies par l'intermédiaire d'Electron pour s'assurer que les contextes restent isolés. Ceci entraîne certaines limitations clés décrites ci-dessous.

Prise en charge des paramètres, erreurs et type de retour

Étant donné que les paramètres, erreurs et valeurs de retour sont copiés lors de leur transmission par le pont, seuls certains types peuvent être utilisés. Mais si le type que vous voulez utiliser peut être sérialisé et désérialisé dans le même objet cela fonctionnera. Une table des types supportés est incluse en complément:

Type	Complexité	Parameter Support	Return Value Support	Limitations
string	Simple	✅	✅	N/A
number	Simple	✅	✅	N/A
boolean	Simple	✅	✅	N/A
Objet	Complexe	✅	✅	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	Complexe	✅	✅	Same limitations as the Object type
Erreur	Complexe	✅	✅	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, and any custom properties on the Error object will be lost
Promise	Complexe	✅	✅	N/A
Function	Complexe	✅	✅	Prototype modifications are dropped. Sending classes or constructors will not work.
Cloneable Types	Simple	✅	✅	See the linked document on cloneable types
Élément	Complexe	✅	✅	Prototype modifications are dropped. L'envoi d'éléments personnalisés ne fonctionnera pas.
Objet blob	Complexe	✅	✅	N/A
Symbole	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.

Exposition des symboles globaux de Node

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.

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')
  }
})