session

Gère les sessions du navigateur, les cookies, le cache, les paramètres de proxy, etc.

Process: Main

Le module session peut être utilisé pour créer des objets Session.

You can also access the session of existing pages by using the session property of WebContents, or from the session module.

const { BrowserWindow } = require('electron')

const win = new BrowserWindow({ width: 800, height: 600 })
win.loadURL('https://github.com')

const ses = win.webContents.session
console.log(ses.getUserAgent())

Méthodes

Le module session dispose des méthodes suivantes :

session.fromPartition(partition[, options])

• partition string
• options Object (facultatif)
  • cache booléen - Indique si il faut activer le cache. Default is true unless the --disable-http-cache switch is used.

Retourne Session - Une instance de session de la chaîne de caractères partition. Quand il y a une Session existante avec la même partition, elle sera retournée; sinon une nouvelle instance Session sera créée avec options.

Si partition commence par persist:, la page utilisera une session persistante disponible pour toutes les pages de l'application avec la même partition. s'il n'y a pas de persist: préfixe, la page utilisera une session en mémoire. Si le partition est vide puis la session par défaut de l'application sera retournée.

Pour créer une Session avec options, vous devez vous assurer que la Session avec la partition n'a jamais été utilisée auparavant. Il n'y a pas moyen de changer les options d'un objet Session existant.

session.fromPath(path[, options])

• path string
• options Object (facultatif)
  • cache booléen - Indique si il faut activer le cache. Default is true unless the --disable-http-cache switch is used.

Retourne une Session - Une instance de session à partir du chemin absolu spécifié par le chemin ficelle. Lorsqu’il existe une Session avec le même chemin absolu, elle sera retourné, sinon une nouvelle instance de Session sera créée avec ses options. L'appel lancera une erreur si le chemin n’est pas un chemin absolu. De plus, une erreur sera levée si une chaîne vide est fournie.

Pour créer une session avec options, vous devez vous assurer que la session avec ce chemin n’a jamais été utilisée auparavant. Il n'y a pas moyen de changer les options d'un objet Session existant.

Propriétés

Le module session dispose des propriétés suivantes :

session.defaultSession

Un objet Session, l'objet d'une session par défaut de l'application.

Classe : Session

Les propriétés getter et setter d'une session.

Process: Main
This class is not exported from the 'electron' module. Elle n'est disponible qu'en tant que valeur de retour des autres méthodes dans l'API Electron.

Vous pouvez créer un objet Session avec le module session :

const { session } = require('electron')
const ses = session.fromPartition('persist:name')
console.log(ses.getUserAgent())

Événements d’instance

Les événements suivants sont disponibles pour les instances de Session :

Événement : 'will-download'

Retourne :

• event Event
• item DownloadItem
• webContents WebContents

Émis lorsque Electron est sur le point de télécharger item dans webContents.

Faire appel à Event.preventDefault () annule le téléchargement et item ne sera pas disponible dans le battement suivant du processus.

const { session } = require('electron')
session.defaultSession.on('will-download', (event, item, webContents) => {
  event.preventDefault()
  require('got')(item.getURL()).then((response) => {
    require('node:fs').writeFileSync('/somewhere', response.body)
  })
})

Événement : 'extension-loaded'

Retourne :

• event Event
• extension Extension

Émis après le chargement d’une extension. Cela se produit chaque fois qu’une extension ajoutée à l’ensemble d’extensions « activées ». Ceci comprend :

• Extensions chargées à partir session.loadExtension.
• Extensions rechargées :
  • à partir d'un plantage.
  • si l'extension l'a demandée (chrome.runtime.reload()).

Événement : 'extension-unloaded'

Retourne :

• event Event
• extension Extension

Émis après le déchargement d’une extension. Cela se produit lorsque Session.removeExtension est appelée.

Événement : 'extension-ready'

Retourne :

• event Event
• extension Extension

Émis après le chargement d’une extension et l’initialisation de tout l’état du navigateur nécessaire pour prendre en charge le démarrage de la page d’arrière-plan de l’extension.

Event: 'file-system-access-restricted'

Retourne :

• event Event
• Objet details
  • origin string - The origin that initiated access to the blocked path.
  • isDirectory boolean - Whether or not the path is a directory.
  • path string - The blocked path attempting to be accessed.
• callback Function
  • action string - The action to take as a result of the restricted path access attempt.
    • allow - This will allow path to be accessed despite restricted status.
    • deny - This will block the access request and trigger an AbortError.
    • tryAgain - This will open a new file picker and allow the user to choose another path.

const { app, dialog, BrowserWindow, session } = require('electron')

async function createWindow () {
  const mainWindow = new BrowserWindow()

  await mainWindow.loadURL('https://buzzfeed.com')

  session.defaultSession.on('file-system-access-restricted', async (e, details, callback) => {
    const { origin, path } = details
    const { response } = await dialog.showMessageBox({
      message: `Are you sure you want ${origin} to open restricted path ${path}?`,
      title: 'File System Access Restricted',
      buttons: ['Choose a different folder', 'Allow', 'Cancel'],
      cancelId: 2
    })

    if (response === 0) {
      callback('tryAgain')
    } else if (response === 1) {
      callback('allow')
    } else {
      callback('deny')
    }
  })

  mainWindow.webContents.executeJavaScript(`
    window.showDirectoryPicker({
      id: 'electron-demo',
      mode: 'readwrite',
      startIn: 'downloads',
    }).catch(e => {
      console.log(e)
    })`, true
  )
}

app.whenReady().then(() => {
  createWindow()

  app.on('activate', () => {
    if (BrowserWindow.getAllWindows().length === 0) createWindow()
  })
})

app.on('window-all-closed', function () {
  if (process.platform !== 'darwin') app.quit()
})

Événement : 'preconnect'

Retourne :

• event Event
• preconnectUrl string - URL demandée pour la préconnexion par le moteur de rendu.
• allowCredentials boolean - Vrai si le moteur de rendu demande que la connexion inclue les identifiants (voir la spécification pour plus de détails.)

Émis lorsqu'un processus de rendu demande de préconnexion à une URL, généralement à cause de un hintressource .

Événement : 'spellcheck-dictionary-initialized'

Retourne :

• event Event
• languageCode string - Code de langue du fichier de dictionnaire

Émis lorsqu'un fichier de dictionnaire hunspell a été initialisé avec succès. Émis après le téléchargement du fichier.

Événement : 'spellcheck-dictionary-download-begin'

Retourne :

• event Event
• languageCode string - Code de langue du fichier de dictionnaire

Émis lors du début de téléchargement d'un fichier de dictionnaire hunspell

Événement : 'spellcheck-dictionary-download-success'

Retourne :

• event Event
• languageCode string - Code de langue du fichier de dictionnaire

Émis lorsqu'un fichier de dictionnaire hunspell a été téléchargé avec succès

Événement : 'spellcheck-dictionary-download-failure'

Retourne :

• event Event
• String languageCode - Code de la langue du fichier de dictionnaire

Émis lorsque le téléchargement d'un fichier de dictionnaire hunspell échoue. Pour plus de détails sur l'échec, vous devriez collecter un log réseau et inspecter la demande de téléchargement.

Événement : 'select-hid-device'

Retourne :

• event Event
• Objet details
  • deviceList HIDDevice[]
  • frame WebFrameMain | null - The frame initiating this event. May be null if accessed after the frame has either navigated or been destroyed.
• callback Function
  • deviceId string | null (optional)

Émis lorsqu'un périphérique HID doit être selectionné lors de l'appel de navigator.hid.requestDevice. callback doit être appelé avec le deviceId à sélectionner, le passage d'une string vide à la callback annulera la requête. De plus, l’autorisation pour navigator.hid peut être gérée en utilisant ses.setPermissionCheckHandler(handler) et ses.setDevicePermissionHandler(handler).

const { app, BrowserWindow } = require('electron')

let win = null

app.whenReady().then(() => {
  win = new BrowserWindow()

  win.webContents.session.setPermissionCheckHandler((webContents, permission, requestingOrigin, details) => {
    if (permission === 'hid') {
      // Ajouter ici la logique déterminant si la sélectioçn HID doir obtenir la permission
      return true
    }
    return false
  })

  // Eventuellemnt récupérer les apareils persistant à partir d'un stockage
  const grantedDevices = fetchGrantedDevices()

  win.webContents.session.setDevicePermissionHandler((details) => {
    if (new URL(details.origin).hostname === 'some-host' && details.deviceType === 'hid') {
      if (details.device.vendorId === 123 && details.device.productId === 345) {
        // Toujours autorise ce type d'appareil (ce qui permet de se passer de l'appel à `navigator.hid.requestDevice` first)
        return true
      }

      // Recherche parmis la liste des appareils aynt déja reçu l'autorisation
      return grantedDevices.some((grantedDevice) => {
        return grantedDevice.vendorId === details.device.vendorId &&
              grantedDevice.productId === details.device.productId &&
              grantedDevice.serialNumber && grantedDevice.serialNumber === details.device.serialNumber
      })
    }
    return false
  })

  win.webContents.session.on('select-hid-device', (event, details, callback) => {
    event.preventDefault()
    const selectedDevice = details.deviceList.find((device) => {
      return device.vendorId === 9025 && device.productId === 67
    })
    callback(selectedDevice?.deviceId)
  })
})

Événement : 'hid-device-added'

Retourne :

• event Event
• Objet details
  • device HIDDevice
  • frame WebFrameMain | null - The frame initiating this event. May be null if accessed after the frame has either navigated or been destroyed.

Émis après l'appel à navigator.hid.requestDevice et le déclenchement de select-hid-device si un nouvel appareil est disponible avant que la callback de select-hid-device ne soit appelée. Cet événement est destiné à être utilisé lors de l'utilisation d'une interface utilisateur demandant aux utilisateurs de choisir un appareil afin que celui-ci puisse être mise à jour avec le périphérique nouvellement ajouté.

Événement : 'hid-device-removed'

Retourne :

• event Event
• Objet details
  • device HIDDevice
  • frame WebFrameMain | null - The frame initiating this event. May be null if accessed after the frame has either navigated or been destroyed.

Émis après l'appel à navigator.hid.requestDevice et le déclenchement de select-hid-device si un nouvel appareil est disponible avant que la callback de select-hid-device ne soit appelée. Cet événement est destiné à être utilisé lors de l'utilisation d'une interface utilisateur demandant aux utilisateurs de choisir un appareil afin que celui-ci puisse être mise à jour avec le périphérique nouvellement ajouté.

Événement : 'hid-device-revoked'

Retourne :

• event Event
• Objet details
  • device HIDDevice
  • origin string (facultatif) - Origine à, partir de laquelle l’appareil a été révoqué.

Émis après que HIDDevice.forget() ai été appelé. Cet événement peut être utilisé pour faciliter le stockage permanent des permissions lorsque setDevicePermissionHandler est utilisé.

Événement : 'select-serial-port'

Retourne :

• event Event
• portList SerialPort[]
• webContents WebContents
• callback Function
  • portId string

Émis lorsqu'un port série doit être sélectionné lorsqu'un appel à navigator.serial.requestPort est effectué. callback doit être appelé avec le portId à sélectionner, le passage d'une string vide à la callback annulera la requête. De plus, la permission sur navigator.serial pourra être gérée en utilisant ses.setPermissionCheckHandler(handler) . avec la permission serial.

const { app, BrowserWindow } = require('electron')

let win = null

app.whenReady(). hen(() => {
  win = new BrowserWindow({
    width: 800,
    height: 600
  })

  win.webContents.session. etPermissionCheckHandler((webContents, permission, requestingOrigin, details) => {
    if (permission === 'serial') {
      // Ajoute une logique ici pour déterminer si l'autorisation doit être donnée pour permettre la sélection en série
      return true
    }
    return false
  })

  // Optionnellement, récupérer des périphériques stockés depuis un magasin persistant
  const accortedDevices = fetchGrantedDevices()

  win. webContents.session.setDevicePermissionHandler((détails) => {
    if (new URL(details.origin). ostname === 'some-host' && details.deviceType === 'serial') {
      if (détails. evice.vendorId === 123 && details.device. roductId === 345) {
        // Toujours autoriser ce type de périphérique (cela permet de ne
  // pas devoir appeller d'abord  `navigator. sérial. equestPort` )
        return true
      }

      // Recherchez dans la liste des périphériques qui ont été précédemment autorisés
      return accordés. ome((accortedDevice) => {
        return grantedDevice. endorId === details.device.vendorId &&
              grantedDevice. roductId === details.device. roductId &&
              accortedDevice. erialNumber && grantedDevice.serialNumber === details.device. erialNumber
      })
    }
    retour faux
  })

  victoire. session eContents.. n('select-serial-port', (event, portList, webContents, callback) => {
    event.preventDefault()
    const selectedPort = portList. ind((device) => {
      return device.vendorId === '9025' && device. roductId === '67'
    })
    if (! electedPort) {
      callback('')
    } else {
      callback(selectedPort. ortId)
    }
  })
})

Événement : 'serial-port-added'

Retourne :

• event Event
• port SerialPort
• webContents WebContents

Émis après l'appel à navigator.serial.requestPort et le déclenchement de select-serial-port si un nouvel appareil est disponible avant que la callback de select-serial-port ne soit appelée. Cet événement est destiné à être utilisé lors de l'utilisation d'une interface utilisateur demandant aux utilisateurs de choisir un appareil afin que celui-ci puisse être mise à jour avec le périphérique nouvellement ajouté.

Événement : 'serial-port-removed'

Retourne :

• event Event
• port SerialPort
• webContents WebContents

Émis après l'appel à navigator.serial.requestPort et le déclenchement de select-serial-port si un nouvel appareil est disponible avant que la callback de select-serial-port ne soit appelée. Cet événement est destiné à être utilisé lors de l'utilisation d'une interface utilisateur demandant aux utilisateurs de choisir un appareil afin que celui-ci puisse être mise à jour avec le périphérique nouvellement ajouté.

Événement : 'serial-port-revoked'

Retourne :

• event Event
• Objet details
  • port SerialPort
  • frame WebFrameMain | null - The frame initiating this event. May be null if accessed after the frame has either navigated or been destroyed.
  • origin string - Origine à, partir de laquelle l’appareil a été révoqué.

Émis après que SerialPort.forget() ai été appelé. Cet événement peut être utilisé pour faciliter le stockage permanent des permissions lorsque setDevicePermissionHandler est utilisé.

// Processus de Navigateur
const { app, BrowserWindow } = require('electron')

app.whenReady().then(() => {
  const win = new BrowserWindow({
    width: 800,
    height: 600
  })

  win.webContents.session.on('serial-port-revoked', (event, details) => {
    console.log(`Access revoked for serial device from origin ${details.origin}`)
  })
})

// Processus de rendu

const portConnect = async () => {
  // Demande un port.
  const port = attendre navigator.serial.requestPort()

  // Attente de l'ouverture du port série.
  await port.open({ baudRate: 9600 })

  // ...plus tard supprime l'acces au port série.
  await port.forget()
}

Événement : 'select-usb-device'

Retourne :

• event Event
• Objet details
  • deviceList USBDevice[]
  • frame WebFrameMain | null - The frame initiating this event. May be null if accessed after the frame has either navigated or been destroyed.
• callback Function
  • deviceId string (facultatif)

Émis lorsqu’un périphérique USB doit être sélectionné lorsque un appel à navigator.usb.requestDevice est effectué. callback doit être appelé avec le deviceId à sélectionner, le passage d'une string vide à la callback annulera la requête. En outre, l’autorisation sur navigator.usb peut être gérée en utilisant ses.setPermissionCheckHandler(handler) et ses.setDevicePermissionHandler(handler).

const { app, BrowserWindow } = require('electron')

let win = null

app.whenReady().then(() => {
  win = new BrowserWindow()

  win.webContents.session.setPermissionCheckHandler((webContents, permission, requestingOrigin, details) => {
    if (permission === 'usb') {
      // Add logic here to determine if permission should be given to allow USB selection
      return true
    }
    return false
  })

  // Optionally, retrieve previously persisted devices from a persistent store (fetchGrantedDevices needs to be implemented by developer to fetch persisted permissions)
  const grantedDevices = fetchGrantedDevices()

  win.webContents.session.setDevicePermissionHandler((details) => {
    if (new URL(details.origin).hostname === 'some-host' && details.deviceType === 'usb') {
      if (details.device.vendorId === 123 && details.device.productId === 345) {
        // Always allow this type of device (this allows skipping the call to `navigator.usb.requestDevice` first)
        return true
      }

      // Search through the list of devices that have previously been granted permission
      return grantedDevices.some((grantedDevice) => {
        return grantedDevice.vendorId === details.device.vendorId &&
              grantedDevice.productId === details.device.productId &&
              grantedDevice.serialNumber && grantedDevice.serialNumber === details.device.serialNumber
      })
    }
    return false
  })

  win.webContents.session.on('select-usb-device', (event, details, callback) => {
    event.preventDefault()
    const selectedDevice = details.deviceList.find((device) => {
      return device.vendorId === 9025 && device.productId === 67
    })
    if (selectedDevice) {
      // Optionally, add this to the persisted devices (updateGrantedDevices needs to be implemented by developer to persist permissions)
      grantedDevices.push(selectedDevice)
      updateGrantedDevices(grantedDevices)
    }
    callback(selectedDevice?.deviceId)
  })
})

Event: 'usb-device-added'

Retourne :

• event Event
• device USBDevice
• webContents WebContents

Émis après l’appel de navigator.usb.requestDevice et que select-usb-device s’est déclenché si un nouveau périphérique est disponible avant que la callback de select-usb-device soit appelée. Cet événement est destiné à être utilisé lors de l'utilisation d'une interface utilisateur demandant aux utilisateurs de choisir un appareil afin que celui-ci puisse être mise à jour avec le périphérique nouvellement ajouté.

Event: 'usb-device-removed'

Retourne :

• event Event
• device USBDevice
• webContents WebContents

Émis après l'appel à navigator.usb.requestDevice et le déclenchement de select-usb-device si un nouvel appareil est disponible avant que la callback de select-usb-device ne soit appelée. Cet événement est destiné à être utilisé lors de l'utilisation d'une interface utilisateur demandant aux utilisateurs de choisir un appareil afin que celui-ci puisse être mise à jour avec le périphérique nouvellement ajouté.

Event: 'usb-device-revoked'

Retourne :

• event Event
• Objet details
  • device USBDevice
  • origin string (facultatif) - Origine à, partir de laquelle l’appareil a été révoqué.

Émis après l'appel à USBDevice.forget(). Cet événement peut être utilisé pour faciliter le stockage permanent des permissions lorsque setDevicePermissionHandler est utilisé.

Méthodes d’instance

Les méthodes suivantes sont disponibles pour les instances de Session :

ses.getCacheSize()

Retourne Promise<Integer> - la taille actuelle du cache de la session, en octets.

ses.clearCache()

Retourne Promise<void> - résout lorsque l'opération de nettoyage du cache est terminée.

Efface le cache HTTP de la session.

ses.clearStorageData([options])

• options Object (facultatif)
  • origin string (facultatif) - Doit suivre le scheme://host:port représentant l' window.location.origin .
  • storages string[] (facultatif) - Types de stockage à effacer, pouvant contenir : cookies, filesystem, indexdb, localstorage, shadercache, websql, serviceworkers, cachestorage, . Si rien n'est spécifié, tous les types de stockage seront nettoyés.
  • quotas string[] (optional) - The types of quotas to clear, can be temporary. Effacez tous les quotas si rien n'est indiqué.

Retourne une Promise<void> - qui se résout lorsque les données de stockage ont été effacées.

ses.flushStorageData()

Écrit toutes les données du DOMStorage non écrites sur le disque.

ses.setProxy(config)

• config ProxyConfig

Retourne une Promise<void> - Elle se résout lorsque l'opération de sélection de proxy est terminée.

Indique les paramètres de proxy.

Vous pourriez avoir besoin de ses.closeAllConnections pour fermer les connexions en cours afin d'empêcher que sockets du pool utilisant un proxy précédant ne soient réutilisées par les futures requêtes.

ses.resolveHost(host, [options])

• host string - Nom d'hôte à résoudre.
• options Object (facultatif)
  • queryType strin (facultatif) - Type de requête DNS demandée. Si non précisé, Le solveur sélectionnera A ou AAAA (ou les deux) en fonction des paramètres IPv4/IPv6 :
    • A - Récupérer uniquement les enregistrements A
    • AAAA - Récupère uniquement les enregistrements AAAA.
  • source string (facultatif) - Source à utiliser pour les adresses résolues. Par défaut le solveur choisira une source appropriée. N'affecte que l'utilisation de sources externes importantes (par exemple, l'appeler au système pour la résolution ou l'utilisation de DNS). Même si une source est spécifiée, les résultats peuvent toujours venir du cache, en résolvant "localhost" ou les litéraux IP, etc. Une des valeurs suivantes:
    • any (par défaut) - Le solveur choisira une source appropriée. Les résultats pouvant de sources telles que DNS, MulticastDNS, fichier HOSTS, etc
    • system - Les résultats ne seront alors récupérés qu'à partir du système ou de l'OS, par ex. via l’appel système à getaddrinfo()
    • dns - Les résultats ne proviendront que des requêtes DNS
    • mdns - Les résultats proviendront uniquement des requêtes DNS Multicast
    • localOnly - Aucune source externe ne sera utilisée. Les résultats ne viendront que à partir des sources locales rapides disponibles, quel que soit le paramètre source, p. ex., cache, fichier hôte, résolution littérale IP, etc.
  • cacheUsage string (facultatif) - Indique quelles entrées de cache DNS, si il en existe pouvant être utilisé pour fournir une réponse. Une des valeurs suivantes:
    • allowed (par défaut) - Les résultats peuvent provenir du cache hôte si le contenu n'est pas pémimé
    • staleAllowed - Les résultats peuvent provenir du cache de l'hôte même si ils sont périmés (par expiration ou changement de réseau)
    • disallowed - Les résultats ne viendront pas du cache de l'hôte.
  • secureDnsPolicy string (facultatif) - Contrôle le comportement du solveur de Secure DNS pour cette requête. Une des valeurs suivantes:
    • allow (par défaut)
    • disable

Returns Promise<ResolvedHost> - Resolves with the resolved IP addresses for the host.

ses.resolveProxy(url)

• url URL

Retourne une Promise<string> - qui se résout avec les informations du proxy pour url.

ses.forceReloadProxyConfig()

Retourne une Promise<void> - qui se résout lorsque tous les états internes du service proxy sont réinitialisés et que la dernière configuration du proxy est réappliquée si elle est déjà disponible. Le script pac sera à nouveau extrait de pacScript si le mode proxy est pac_script.

ses.setDownloadPath(path)

• path string - Emplacement du téléchargement.

Définit le répertoire de sauvegarde des téléchargements. Par défaut, le répertoire de téléchargement sera le Telechargements dans le dossier d'application respectif.

ses.enableNetworkEmulation(options)

• Objet options
  • offline boolean (optionelle) - Émuler une panne de réseau. false par défaut.
  • latency Double (facultatif) - RTT en ms. 0 par défaut, ce qui désactive la limitation de latence.
  • downloadThroughput Double (facultatif) - vitesse de téléchargement en Bps. La valeur par défaut est 0 qui désactive la limitation de téléchargement.
  • uploadThroughput Double (facultatif) - vitesse de téléversement en Bps. La valeur par défaut est 0 qui désactive la limitation.

Emule le réseau avec la configuration donnée pour la session.

const win = new BrowserWindow()

// Pour émuler une connexion GPRS avec un débit de 50kbps et une latence de 500 ms.
win.webContents.session.enableNetworkEmulation({
  latency: 500,
  downloadThroughput: 6400,
  uploadThroughput: 6400
})

// Pour émuler une panne de réseau.
win.webContents.session.enableNetworkEmulation({ offline: true })

ses.preconnect(options)

• Objet options
  • url string - URL pour la préconnexion. Seule l'origine est pertinente pour l'ouverture du socket.
  • numSockets number (facultatif) - nombre de sockets à préconnecter. Doit être compris entre 1 et 6. 1 par défaut.

Préconnecte le nombre de sockets donné pour une origine.

ses.closeAllConnections()

Retourne Promise<void> - qui se résout lorsque toutes les connexions sont fermées.

[!NOTE] It will terminate / fail all requests currently in flight.

ses.fetch(input[, init])

• input string | GlobalRequest
• init RequestInit & { bypassCustomProtocolHandlers?: boolean } (optional)

Returns Promise<GlobalResponse> - see Response.

Sends a request, similarly to how fetch() works in the renderer, using Chrome's network stack. This differs from Node's fetch(), which uses Node.js's HTTP stack.

Exemple :

async function example () {
  const response = await net.fetch('https://my.app')
  if (response.ok) {
    const body = await response.json()
    // ... utilisation du résultat.
  }
}

See also net.fetch(), a convenience method which issues requests from the default session.

See the MDN documentation for fetch() for more details.

Limitations:

• net.fetch() ne prend pas en charge les schémas data: ou blob:.
• La valeur de l'option integrity est ignorée.
• Les valeurs .type et .url de l'objet Response retourné sont incorrectes.

By default, requests made with net.fetch can be made to custom protocols as well as file:, and will trigger webRequest handlers if present. When the non-standard bypassCustomProtocolHandlers option is set in RequestInit, custom protocol handlers will not be called for this request. This allows forwarding an intercepted request to the built-in handler. webRequest handlers will still be triggered when bypassing custom protocols.

protocol.handle('https', (req) => {
  if (req.url === 'https://my-app.com') {
    return new Response('<body>my app</body>')
  } else {
    return net.fetch(req, { bypassCustomProtocolHandlers: true })
  }
})

ses.disableNetworkEmulation()

Désactive toute émulation de réseau déjà active pour la session. Réinitialise à la configuration réseau initiale.

ses.setCertificateVerifyProc(proc)

• proc Function | null
  • request Object
    • hostname string
    • certificate Certificate
    • validatedCertificate Certificate
    • isIssuedByKnownRoot booléen - true si Chromium reconnaît le CA racine comme une racine standard. Si ce n'est pas le cas, il est probable que ce certificat ait été généré par un proxy MITM dont la racine a été installée localement (par exemple, par un proxy d'entreprise). Cela ne devrait pas être approuvé si le verificationResult n'est pas OK.
    • verificationResult string - OK si le certificat est approuvé, sinon une erreur comme CERT_REVOKED.
    • errorCode Integer - Code d'erreur.
  • callback Function
    • verificationResult Entier - La valeur peut être l’un des codes d’erreur de certificat que l'on peut trouver ici. En dehors des codes d'erreur du certificat, les codes spéciaux suivants peuvent être utilisés.
      • 0 - Indique la réussite et désactive la vérification de transparence de certificat.
      • -2 - Indique l'échec.
      • -3 - Utilise le résultat de la vérification de Chromium.

Définit le proc de vérification du certificat pour session, le proc sera appelé avec proc(request, callback) chaque fois qu'une vérification de certificat de serveur est demandée. L'appel à callback(0) accepte le certificat, appeler callback(-2) le rejette.

L'appel à setCertificateVerifyProc(null) réinitialisera au proc de vérification du certificat par défaut.

const { BrowserWindow } = require('electron')
const win = new BrowserWindow()

win.webContents.session.setCertificateVerifyProc((request, callback) => {
  const { hostname } = request
  if (hostname === 'github.com') {
    callback(0)
  } else {
    callback(-2)
  }
})

REMARQUE : Le résultat de cette procédure est mis en cache par le service réseau.

ses.setPermissionRequestHandler(handler)

• handler Function | null
  • webContents WebContents - WebContents requesting the permission. Veuillez noter que si la demande provient d'une sous-frame, vous devez utiliser requestingUrl pour vérifier l'origine de la demande.
  • permission string - Type d’autorisation demandée.
    • clipboard-read - Demande d'accès à la lecture depuis le presse-papiers.
    • clipboard-sanitized-write - Demande d'accès à l'écriture dans le presse-papiers.
    • display-capture - Demande d’accès pour capturer l’écran via l’API Screen Capture.
    • fullscreen - Request control of the app's fullscreen state via the Fullscreen API.
    • geolocation - Request access to the user's location via the Geolocation API
    • idle-detection - Request access to the user's idle state via the IdleDetector API.
    • média - Demande l'accès à des périphériques multimédia tels que la caméra, le microphone et les haut-parleurs.
    • mediaKeysystem - Demande d’accès au contenu protégé par DRM.
    • midi - Request MIDI access in the Web MIDI API.
    • midiSysex - Request the use of system exclusive messages in the Web MIDI API.
    • notifications - Request notification creation and the ability to display them in the user's system tray using the Notifications API
    • pointerLock - Request to directly interpret mouse movements as an input method via the Pointer Lock API. Ces requêtes semblent toujours provenir de la frame principale.
    • keyboardLock - Request capture of keypresses for any or all of the keys on the physical keyboard via the Keyboard Lock API. Ces requêtes semblent toujours provenir de la frame principale.
    • openExternal - Demande d’ouverture de liens dans des applications externes.
    • speaker-selection - Request to enumerate and select audio output devices via the speaker-selection permissions policy.
    • storage-access - Allows content loaded in a third-party context to request access to third-party cookies using the Storage Access API.
    • top-level-storage-access - Allow top-level sites to request third-party cookie access on behalf of embedded content originating from another site in the same related website set using the Storage Access API.
    • window-management - Demande l'accès à l'énumération des écrans en utilisant l'API getScreenDetails.
    • unknown - Demande d’autorisation non reconnue.
    • fileSystem - Request access to read, write, and file management capabilities using the File System API.
  • callback Function
    • permissionGranted booléen - Autoriser ou refuser la permission.
  • details PermissionRequest | FilesystemPermissionRequest | MediaAccessPermissionRequest | OpenExternalPermissionRequest - Additional information about the permission being requested.

Définit le gestionnaire qui peut être utilisé pour répondre aux vérifications de permissions pour la session. L'appeler à callback(true) autorisera la permission et callback(false) le rejettera. Pour supprimer le gestionnaire, appelez setPermissionRequestHandler(null). Veuillez noter que vous devez également implémenter setPermissionCheckHandler pour obtenir la gestion complète des permissions. La plupart des API web font une vérification des permissions, puis, si la vérification est refusée, font une demande de permission .

const { session } = require('electron')
session.fromPartition('some-partition').setPermissionRequestHandler((webContents, permission, callback) => {
  if (webContents.getURL() === 'some-host' && permission === 'notifications') {
    return callback(false) // interdit.
  }

  callback(true)
})

ses.setPermissionCheckHandler(handler)

• handler Function<boolean> | null
  • webContents (WebContents | null) - WebContents checking the permission. Veuillez noter que si la demande provient d'une sous-frame, vous devez utiliser requestingUrl pour vérifier l'origine de la demande. Toutes les frames de cross origin effectuant des vérifications de permission passeront un null webContents à ce gestionnaire, alors que certaines autres vérifications de permissions, telles que notifications , passeront toujours null. Vous devez utiliser embeddingOrigin et requestingOrigin pour déterminer quelles sont respectivement la frame propriétaire et celle effectuant la demande.
  • permission string - Type de vérification des permissions.
    • clipboard-read - Demande d'accès à la lecture depuis le presse-papiers.
    • clipboard-sanitized-write - Demande d'accès à l'écriture dans le presse-papiers.
    • géolocalisation - Accéde aux données de géolocalisation de l’utilisateur via l’API Géolocalisation
    • fullscreen - Gère l’état plein écran de l’application via l'API plein écran.
    • hid - Access the HID protocol to manipulate HID devices via the WebHID API.
    • idle-detection - Access the user's idle state via the IdleDetector API.
    • media - Access to media devices such as camera, microphone and speakers.
    • mediaKeySystem - Access to DRM protected content.
    • midi - Enable MIDI access in the Web MIDI API.
    • midiSysex - Use system exclusive messages in the Web MIDI API.
    • notifications - Configure and display desktop notifications to the user with the Notifications API.
    • openExternal - Open links in external applications.
    • pointerLock - Directly interpret mouse movements as an input method via the Pointer Lock API. Ces requêtes semblent toujours provenir de la frame principale.
    • serial - Read from and write to serial devices with the Web Serial API.
    • storage-access - Allows content loaded in a third-party context to request access to third-party cookies using the Storage Access API.
    • top-level-storage-access - Allow top-level sites to request third-party cookie access on behalf of embedded content originating from another site in the same related website set using the Storage Access API.
    • usb - Expose non-standard Universal Serial Bus (USB) compatible devices services to the web with the WebUSB API.
    • deprecated-sync-clipboard-read Deprecated - Request access to run document.execCommand("paste")
  • requestingOrigin string - URL d'origine de la vérification des permissions
  • Objet details - Certaines propriétés ne sont disponibles que sur certains types de permissions.
    • embeddingOrigin string (optionelle) - L'origine de la frame incorporant la frame ayant effectué la vérification des permissions. Est uniquement defini pour les sous-frames cross--origin qui effectuent des vérifications d'autorisation.
    • securityOrigin string (optionelle) - L'origine de sécurité de la vérification de media.
    • mediaType string (facultatif) - Le type de média demandé peut être video, audio ou unknown
    • requestingUrl string (optionelle) - Dernière URL que la frame faisant la demande a chargé. Ceci n'est pas prévu pour les sub-frames cross-origin effectuant des vérifications d'autorisation.
    • isMainFrame booléen - Indique sir la frame à l'origine de la requête est la frame principale

Définit le gestionnaire qui peut être utilisé pour répondre aux vérifications de permissions pour la session. Retourne true pour autoriser la permission et false pour la rejetter. Veuillez noter que vous devez également implémenter setPermissionRequestHandler pour obtenir la gestion complète des permissions. La plupart des API web font une vérification des permissions, puis, si la vérification est refusée, font une demande de permission . Pour effacer le gestionnaire, appelez setPermissionCheckHandler(null).

const { session } = require('electron')
const url = require('url')
session.fromPartition('some-partition').setPermissionCheckHandler((webContents, permission, requestingOrigin) => {
  if (new URL(requestingOrigin).hostname === 'some-host' && permission === 'notifications') {
    return true // granted
  }

  return false // denied
})

ses.setDisplayMediaRequestHandler(handler[, opts])

• handler Function | null
  • request Object
    • frame WebFrameMain | null - Frame that is requesting access to media. May be null if accessed after the frame has either navigated or been destroyed.
    • securityOrigin String - Origine de la page faisant la demande.
    • videoRequested Booléen - true si le contenu web a demandé un flux vidéo.
    • audioRequested Booléen - true si le contenu Web a demandé un flux audio.
    • userGesture Booléen - Indique si un geste utilisateur était actif quand cette requête a été déclenchée.
  • callback Function
    • Object streams
      • video Object | WebFrameMain (optional)
        • id String - id du flux en cours d'autorisation. This will usually come from a DesktopCapturerSource object.
        • name String - Nom du flux en cours d'autorisation. This will usually come from a DesktopCapturerSource object.
      • audio String | WebFrameMain (optional) - If a string is specified, can be loopback or loopbackWithMute. Spécifier un périphérique de rebouclage va capturer l'audio du système et n'est actuellement pris en charge que sur Windows. Si une WebFrameMain est spécifiée, capturera l'audio à partir de cette frame.
      • enableLocalEcho Boolean (optional) - If audio is a WebFrameMain and this is set to true, then local playback of audio will not be muted (e.g. using MediaRecorder to record WebFrameMain with this flag set to true will allow audio to pass through to the speakers while recording). Par défaut la valeur est false.
• opts Object (optional) macOS Experimental
  • useSystemPicker Boolean - true if the available native system picker should be used. Par défaut la valeur est false. macOS Experimental

Ce gestionnaire sera appelé lorsque le contenu Web demande l'accès pour afficher les médias via l'API navigator.mediaDevices.getDisplayMedia. Use the desktopCapturer API to choose which stream(s) to grant access to.

useSystemPicker allows an application to use the system picker instead of providing a specific video source from getSources. This option is experimental, and currently available for MacOS 15+ only. If the system picker is available and useSystemPicker is set to true, the handler will not be invoked.

const { session, desktopCapturer } = require('electron')

session.defaultSession.setDisplayMediaRequestHandler((request, callback) => {
  desktopCapturer. etSources({ types: ['screen'] }).then((sources) => {
    // Autoriser l'accès au premier screen trouvé.
    callback({ video: sources[0] })
  })
  // Use the system picker if available.
  // Note: this is currently experimental. If the system picker
  // is available, it will be used and the media request handler
  // will not be invoked.
}, { useSystemPicker: true })

Passing a WebFrameMain object as a video or audio stream will capture the video or audio stream from that frame.

const { session } = require('electron')

session.defaultSession.setDisplayMediaRequestHandler((request, callback) => {
  // Permet à l'onglet de se capturer lui même.
  callback({ video: request.frame })
})

Le passage de null au lieu d'une fonction réinitialise le gestionnaire à son état par défaut.

ses.setDevicePermissionHandler(handler)

• handler Function<boolean> | null
  • Objet details
    • deviceType string - Type de périphérique pour lequel la permission est demandée, peut être hid , serial ou usb.
    • origin string - URL à l'origine de la demande de vérification d'autorisation du périphérique.
    • device HIDDevice | SerialPort | USBDevice - the device that permission is being requested for.

Définit le gestionnaire pouvant être utilisé pour répondre aux vérifications des permissions de l'appareil pour la session. Retourner true permettra à l'appareil d'être autorisé et false le rejettera. Pour supprimer le gestionnaire, appelez setDevicePermissionHandler(null). Ce gestionnaire peut être utilisé pour fournir des autorisations par défaut aux appareils sans avoir d'abord demandé celle ci (par exemple via navigator.hid.requestDevice). Si ce gestionnaire n'est pas défini, les permissions par défaut accordées via la sélection de l'appareil (par exemple via navigator.hid.requestDevice) seront utilisées. De plus, le comportement par défaut d'Electron est de stocker dans la mémoire la permission accordée au périphérique. Si un stockage à plus long terme est nécessaire, le développeur peut stocker les autorisations accordées au périphérique (par exemple lors de la gestion de l'événement select-hid-device ) pour ensuite les lire depuis ce stockage avec setDevicePermissionHandler.

const { app, BrowserWindow } = require('electron')

let win = null

app.whenReady().then(() => {
  win = new BrowserWindow()

  win.webContents.session.setPermissionCheckHandler((webContents, permission, requestingOrigin, details) => {
    if (permission === 'hid') {
      // Ajoutez une logique ici pour déterminer si l'autorisation doit être accordée pour autoriser la sélection HID
      return true
    } else if (permission === 'serial') {
      // Ajoutez une logique ici pour déterminer si l'autorisation doit être accordée pour autoriser la sélection du port série
    } else if (permission === 'usb') {
      // Ajoutez une logique ici pour déterminer si l'autorisation doit être accordée pour autoriser la sélection de périphériques USB
    }
    return false
  })

  // Facultativement, récupérez les appareils précédemment persistants à partir d'un magasin persistant
  const grantedDevices = fetchGrantedDevices()

  win.webContents.session.setDevicePermissionHandler((details) => {
    if (new URL(details.origin).hostname === 'some-host' && details.deviceType === 'hid') {
      if (details.device.vendorId === 123 && details.device.productId === 345) {
        // Autorisez toujours ce type d'appareil (cela permet de sauter d'abord l'appel à `navigator.hid.requestDevice`)
        return true
      }

      // Recherchez dans la liste des appareils qui ont déjà reçu une autorisation
      return grantedDevices.some((grantedDevice) => {
        return grantedDevice.vendorId === details.device.vendorId &&
              grantedDevice.productId === details.device.productId &&
              grantedDevice.serialNumber && grantedDevice.serialNumber === details.device.serialNumber
      })
    } else if (details.deviceType === 'serial') {
      if (details.device.vendorId === 123 && details.device.productId === 345) {
        // Autorisez toujours ce type d'appareil (cela permet de sauter d'abord l'appel à `navigator.hid.requestDevice`)
        return true
      }
    }
    return false
  })

  win.webContents.session.on('select-hid-device', (event, details, callback) => {
    event.preventDefault()
    const selectedDevice = details.deviceList.find((device) => {
      return device.vendorId === 9025 && device.productId === 67
    })
    callback(selectedDevice?.deviceId)
  })
})

ses.setUSBProtectedClassesHandler(handler)

• handler Function<string[]> | null
  • Objet details
    • protectedClasses string[] - La liste actuelle des classes USB protégées. Les valeurs possibles de la classe sont les suivantes:
      • audio
      • audio-video
      • hid
      • mass-storage
      • smart-card
      • video
      • wireless

Sets the handler which can be used to override which USB classes are protected. La valeur retournée pour le gestionnaire est un tableau de chaînes de caractères des classes USB qui doivent être considérées comme protégées (par exemple non disponibles dans le moteur de rendu). Les valeurs valides dans le tableau sont:

• audio
• audio-video
• hid
• mass-storage
• smart-card
• video
• wireless

Retourner un tableau de chaînes vide depuis le gestionnaire autorisera toutes les classes USB ; retourner le tableau passé maintiendra la liste par défaut des classes USB protégées (c'est aussi le comportement par défaut si un gestionnaire n'est pas défini). Pour effacer le gestionnaire, appelez setUSBProtectedClassesHandler(null).

const { app, BrowserWindow } = require('electron')

let win = null

app.whenReady().then(() => {
  win = new BrowserWindow()

  win.webContents.session.setUSBProtectedClassesHandler((details) => {
    // Autoriser toutes les classes:
    // return []
    // Conserver le jeu de classes protégées:
    // return details.protectedClasses
    // Supprimer séléctivement certaines classes:
    return details.protectedClasses.filter((usbClass) => {
      // Exclusion des classes sauf de celles audio 
      return usbClass.indexOf('audio') === -1
    })
  })
})

ses.setBluetoothPairingHandler(handler) Windows Linux

• handler Function | null
  • Objet details
    • deviceId string
    • pairingKind string -Type de l'invite d'appairage demandé. Une des valeurs suivantes:
      • confirm Cette invite demande la confirmation que le périphérique Bluetooth doit être apparié.
      • confirmPin Cette invite demande la confirmation que le code PIN fourni correspond au code affiché sur l'appareil.
      • providePin Cette invite demande qu'un code soit fourni pour le périphérique.
    • frame WebFrameMain | null - The frame initiating this handler. May be null if accessed after the frame has either navigated or been destroyed.
    • pin string (facultatif) - Valeur du code Pin à vérifier si pairingKind est confirmPin.
  • callback Function
    • Objet response
      • confirmed booléen - false doit être passé si la boîte de dialogue est annulée. Si le pairingKind est confirm ou confirmPin, cette valeur doit indiquer si le jumelage est confirmé. Si le pairingKind est providePin, doit être à true lorsqu'une valeur est fournie.
      • pin string | null (optionelle) - Lorsque le pairingKind est providePin cette valeur doit être le PIN requis pour le périphérique Bluetooth.

Définit un gestionnaire pour répondre aux demandes d'appairage Bluetooth. Ce gestionnaire permet aux développeurs de gérer les périphériques qui nécessitent une validation supplémentaire avant de s'appairer. Lorsqu'un gestionnaire n'est pas défini, toute appairage sous Linux ou Windows nécessitant une validation supplémentaire sera automatiquement annulée. macOS ne nécessite pas de gestionnaire car il gère le jumelage automatiquement. Pour supprimer le gestionnaire, appelez setBluetoothPairingHandler(null).

const { app, BrowserWindow, session } = require('electron')
const path = require('node:path')

function createWindow () {
  let bluetoothPinCallback = null

  const mainWindow = new BrowserWindow({
    webPreferences: {
      preload: path.join(__dirname, 'preload.js')
    }
  })

  mainWindow.webContents.session.setBluetoothPairingHandler((details, callback) => {
    bluetoothPinCallback = callback
    // Envoyez un message IPC au moteur de rendu pour inviter l'utilisateur à confirmer le couplage.
    // Notez que cela nécessitera dans le moteur de rendu du code pour gérer ce message et 
  // l'affichage d'une invite à l'utilisateur.
    mainWindow.webContents.send('bluetooth-pairing-request', details)
  })

  // Ecoute d'un message IPC message du coté moteur de rendu afin d'obtenir une réponse de l'appairage Bluetooth.
  mainWindow.webContents.ipc.on('bluetooth-pairing-response', (event, response) => {
    bluetoothPinCallback(response)
  })
}

app.whenReady().then(() => {
  createWindow()
})

ses.clearHostResolverCache()

Retourne une Promise<void> - Elle se résout lorsque l'opération est terminée.

Vide le cache de résolution de l'hôte.

ses.allowNTLMCredentialsForDomains(domains)

• domains string - Liste séparés par des virgules de serveurs pour lesquels l'authentification intégrée est activée.

Définit dynamiquement s'il faut toujours envoyer des identifiants pour l'authentification HTTP NTLM ou Négocier .

const { session } = require('electron')
// considère n'importe quelle url se terminant par `example.com`, `foobar.com`, `baz`
// pour une authentification intégrée.
session.defaultSession.allowNTLMCredentialsForDomains('*example.com, *foobar.com, *baz')

// considère toutes les urls pour une authentification intégrée.
session.defaultSession.allowNTLMCredentialsForDomains('*')

ses.setUserAgent(userAgent[, acceptLanguages])

• userAgent string
• acceptLanguages string (facultatif)

Remplace les userAgent et acceptLanguages pour cette session.

Le acceptLanguages doit être une liste ordonnée de codes de langue séparés par des virgules, pour exemple "en-US,fr,de,ko,zh-CN,ja".

Cela n'affecte pas les WebContents, et chaque WebContents peut utiliser webContents.setUserAgent pour remplacer l'agent utilisateur à l'échelle de la session.

ses.isPersistent()

Retourne boolean - Indique si cette session est persistante ou non. Par défaut, la session du webContents d'une BrowserWindow est persistante. Lors de la création d'une session à partir d'une partition, les sessions préfixées avec persist: seront persistantes, tandis que les autres seront temporaires.

ses.getUserAgent()

Renvoie string - L'user agent de cette session.

ses.setSSLConfig(config)

• config Object
  • minVersion string (facultatif) - Peut être tls1, tls1.1, tls1.2 ou tls1.3. La version minimale SSL à autoriser lors de la connexion à des serveurs distants. tls1 par défaut.
  • maxVersion string (facultatif) -Peut être tls1.2 ou tls1.3. La version SSL maximale à autoriser lors de la connexion à des serveurs distants. tls1.3 par défaut.
  • disabledCipherSuites Integer[] (optionelle) - Liste des suites de chiffrement qui doivent être empêchées explicitement d'être utilisées en plus de celles désactivées par la politique intégrée du réseau. Formes littérales supportées : 0xAABB, où AA est cipher_suite[0] et BB est cipher_suite[1], tel que défini dans RFC 2246, Section 7.4.1.2. Les suites de chiffrement non reconnues mais analysables dans ce formulaire ne retourneront pas d'erreur. Ex: Pour désactiver TLS_RSA_WITH_RC4_128_MD5, spécifiez 0x0004, tandis que pour désactiver TLS_ECDH_ECDSA_WITH_RC4_128_SHA, spécifiez 0xC002. Notez que les chiffrements TLSv1.3 ne peuvent pas être désactivés en utilisant ce mécanisme.

Définit la configuration SSL pour la session. Toutes les requêtes réseau suivantes utiliseront cette nouvelle configuration. Les connexions réseau existantes (telles que les connexions WebSocket) ne seront pas cloturées, mais les anciennes sockets dans le pool ne seront pas réutilisées pour de nouvelles connexions.

ses.getBlobData(identifier)

• identifier string - UUID valide.

Returns Promise<Buffer> - resolves with blob data.

ses.downloadURL(url[, options])

• url string
• options Object (facultatif)
  • headers Record<string, string> (facultatif) - En-têtes de requête HTTP.

Lance le téléchargement de la ressource située à l'url. The API will generate a DownloadItem that can be accessed with the will-download event.

[!NOTE] This does not perform any security checks that relate to a page's origin, unlike webContents.downloadURL.

ses.createInterruptedDownload(options)

• Objet options
  • path string - Chemin d'accès absolu pour le téléchargement.
  • urlChain string[] - Chaîne de caractère complète de l'URL du téléchargement.
  • mimeType string (facultatif)
  • offset Integer - Portée de départ pour le téléchargement.
  • length Integer - Longueur totale du le téléchargement.
  • lastModified string (facultatif) - Valeur de l'en-tête Last-Modified.
  • eTag string (facultatif) - Valeur de l'en-tête ETag.
  • startTime Double (facultatif) - Heure du début de téléchargement, en nombre de secondes depuis la date initiale UNIX (1er janvier 1970 à 0 heure (UTC)).

Autorise la reprise des téléchargements cancelled (annulés) ou interrupted (interrompus) depuis la Session précédente. The API will generate a DownloadItem that can be accessed with the will-download event. Le DownloadItem n'aura aucun WebContents associé et l'état initial sera interrupted. The download will start only when the resume API is called on the DownloadItem.

ses.clearAuthCache()

Retourne Promise<void> - résout lorsque le cache d'authentification HTTP de la session a été effacé.

ses.setPreloads(preloads) __ obsolète

• preloads string[] - Tableau des chemins absolus des scripts de preload

Ajoute des scripts qui seront exécutés sur TOUS les contenus web qui sont associés à cette session et ceci juste avant l'exécution normale des scripts de preload.

Deprecated: Use the new ses.registerPreloadScript API.

ses.getPreloads() __ obsolète

Retourne string[] un tableau des chemins des scripts de preload enregistrés.

Deprecated: Use the new ses.getPreloadScripts API. This will only return preload script paths for frame context types.

ses.registerPreloadScript(script)

• script PreloadScriptRegistration - Preload script

Registers preload script that will be executed in its associated context type in this session. For frame contexts, this will run prior to any preload defined in the web preferences of a WebContents.

Returns string - The ID of the registered preload script.

ses.unregisterPreloadScript(id)

• id string - Preload script ID

Unregisters script.

ses.getPreloadScripts()

Returns PreloadScript[]: An array of paths to preload scripts that have been registered.

ses.setCodeCachePath(path)

• path String - Chemin absolu pour stocker le cache de code JS généré par v8.

Sets the directory to store the generated JS code cache for this session. Le répertoire n'a pas besoin d'être forcemment créé par l'utilisateur avant cet appel, le runtime créera le répertoire s'il n'existe pas sinon il utilisera le répertoire existant. Si le répertoire ne peut pas être créé, le cache de code ne sera pas utilisé et toutes les opérations liées au cache de code échoueront silencieusement. Par défaut, le répertoire sera Code Cache sous le dossier respectif des donéées de l'utilisateur.

Notez que par défaut, le cache de code n’est activé que pour les URL http(s), pour l'activer pour les protocoles personnalisés, codeCache : true et standard : true doivent être spécifié lors de l’enregistrement du protocole.

ses.clearCodeCaches(options)

• Objet options
  • urls String[] (facultatif) - Tableau d'urls correspondant à la ressource dont le cache de code généré doit être supprimé. Si la liste est vide, toutes les entrées du répertoire de cache seront supprimées.

Retourne Promise<void> -qui se résout lorsque l'opération de nettoyage du cache est terminée.

ses.getSharedDictionaryUsageInfo()

Returns Promise<SharedDictionaryUsageInfo[]> - an array of shared dictionary information entries in Chromium's networking service's storage.

Shared dictionaries are used to power advanced compression of data sent over the wire, specifically with Brotli and ZStandard. You don't need to call any of the shared dictionary APIs in Electron to make use of this advanced web feature, but if you do, they allow deeper control and inspection of the shared dictionaries used during decompression.

To get detailed information about a specific shared dictionary entry, call getSharedDictionaryInfo(options).

ses.getSharedDictionaryInfo(options)

• Objet options
  • frameOrigin string - The origin of the frame where the request originates. It’s specific to the individual frame making the request and is defined by its scheme, host, and port. In practice, will look like a URL.
  • topFrameSite string - The site of the top-level browsing context (the main frame or tab that contains the request). It’s less granular than frameOrigin and focuses on the broader "site" scope. In practice, will look like a URL.

Returns Promise<SharedDictionaryInfo[]> - an array of shared dictionary information entries in Chromium's networking service's storage.

To get information about all present shared dictionaries, call getSharedDictionaryUsageInfo().

ses.clearSharedDictionaryCache()

Returns Promise<void> - resolves when the dictionary cache has been cleared, both in memory and on disk.

ses.clearSharedDictionaryCacheForIsolationKey(options)

• Objet options
  • frameOrigin string - The origin of the frame where the request originates. It’s specific to the individual frame making the request and is defined by its scheme, host, and port. In practice, will look like a URL.
  • topFrameSite string - The site of the top-level browsing context (the main frame or tab that contains the request). It’s less granular than frameOrigin and focuses on the broader "site" scope. In practice, will look like a URL.

Returns Promise<void> - resolves when the dictionary cache has been cleared for the specified isolation key, both in memory and on disk.

ses.setSpellCheckerEnabled(enable)

• enable boolean

Définit s'il faut activer le correcteur orthographique intégré.

ses.isSpellCheckerEnabled()

boolean indique si le correcteur orthographique interne est activé.

ses.setSpellCheckerLanguages(languages)

• languages string[] - Tableau des codes de langue pour lesquels vérificateur d'orthographe sera activé.

Le correcteur orthographique intégré ne détecte pas automatiquement la langue dans laquelle un utilisateur tape. Afin que le correcteur orthographique vérifie correctement les mots, vous devez exécuter cette API avec un tableau de codes de langue. Vous pouvez obtenir la liste des codes de langue pris en charge avec la propriété ses.availableSpellCheckerLanguages.

[!NOTE] On macOS, the OS spellchecker is used and will detect your language automatically. Cette API est sans aucun effet sur macOS.

ses.getSpellCheckerLanguages()

Retourne string[] - Un tableau de codes de langue pour lesquels le correcteur orthographique est activé. Si cette liste est vide, le correcteur orthographique utilisera en-US. Par défaut au lancement si ce paramètre est une liste vide, Electron essaiera de remplir ce paramètre avec la locale actuelle de l'OS. Ce paramètre est maintenu lors de redémarrage.

[!NOTE] On macOS, the OS spellchecker is used and has its own list of languages. Sur macOS, cette API retournera les langues qui ont été configurées par l'OS.

ses.setSpellCheckerDictionaryDownloadURL(url)

• url string - Une URL de base à partir de laquelle Electron peut télécharger des dictionnaires hunspell.

Par défaut, Electron téléchargera les dictionnaires hunspell à partir du CDN Chromium. Si vous voulez remplacer ce comportement vous pouvez utiliser cette API pour pointer le téléchargeur de dictionnaire sur votre propre version hébergée des dictionnaires hunspell. Avec chaque version, nous publions un fichier hunspell_dictionaries.zip contenant les fichiers dont vous avez besoin pour l'héberger .

The file server must be case insensitive. Si ce n'est pas le cas, vous devez télécharger chaque fichier deux fois : une fois avec la casse du fichier ZIP et une autre fois avec le nom du fichier toute en minuscule.

Si les fichiers présents dans hunspell_dictionaries.zip sont disponibles à https://example.com/dictionaries/language-code.bdic alors vous devrez appeler cette api avec ses.setSpellCheckerDictionaryDownloadURL('https://example.com/dictionaries/'). Veuillez noter la barre oblique de fin. L'URL des dictionnaires est sous la forme ${url}${filename}.

[!NOTE] On macOS, the OS spellchecker is used and therefore we do not download any dictionary files. Cette API est sans aucun effet sur macOS.

ses.listWordsInSpellCheckerDictionary()

Retourne Promise<string[]> - Un tableau de tous les mots du dictionnaire personnalisé de l'application. Elle se résout lorsque le dictionnaire complet est chargé à partir du disque.

ses.addWordToSpellCheckerDictionary(word)

• String word - Le mot que vous voulez ajouter au dictionnaire

Retourne boolean - Indique si le mot a été écrit avec succès dans le dictionnaire personnalisé. Cette API ne fonctionnera pas sur des sessions non persistantes (en mémoire).

[!NOTE] On macOS and Windows, this word will be written to the OS custom dictionary as well.

ses.removeWordFromSpellCheckerDictionary(word)

• String word - Le mot que vous voulez supprimer du dictionnaire

Retourne boolean - Si le mot a été supprimé avec succès dans le dictionnaire personnalisé. Cette API ne fonctionnera pas sur des sessions non persistantes (en mémoire).

[!NOTE] On macOS and Windows, this word will be removed from the OS custom dictionary as well.

ses.loadExtension(path[, options]) __ obsolète

• String path - Chemin vers un répertoire contenant une extension Chrome décompressée
• options Object (facultatif)
  • allowFileAccess boolean - Permet à l'extension de lire des fichiers locaux sous le protocole file:// et d'injecter des scripts de contenu dans file://. Ceci est requis par exemple pour charger les extensions devtools sur les URLs file://. false par défaut.

Returns Promise<Extension> - resolves when the extension is loaded.

Cette méthode déclenche une exception si l’extension n’a pas pu être chargée. Si il y a des avertissements lors de l'installation de l'extension (par ex. si l'extension utilise une API non prise en charge par Electron) ceux-ci seront enregistrés dans la console.

Notez qu'Electron ne prend pas en charge la gamme complète des API d'extensions Chrome. See Supported Extensions APIs for more details on what is supported.

Notez que dans les versions précédentes d'Electron, les extensions qui avaient été chargées etaient mémorisées pour les exécutions futures de l'application. Ce n'est plus le cas : loadExtension doit être appelé à chaque démarrage de votre application si vous voulez que l'extension soit chargée.

const { app, session } = require('electron')
const path = require('node:path')

app.whenReady().then(async () => {
  await session.defaultSession.loadExtension(
    path.join(__dirname, 'react-devtools'),
    // allowFileAccess est requis pour charger l'extension devtools sur les URL file://.
    { allowFileAccess: true }
  )
  // Notez que pour utiliser l'extension React DevTools, vous aurez besoin de
  // télécharger et décompresser une copie de l'extension.
})

Cette API ne supporte pas le chargement des extensions compressées (.crx).

[!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.

Deprecated: Use the new ses.extensions.loadExtension API.

ses.removeExtension(extensionId) __ obsolète

• extensionId string - ID de l'extension à supprimer

Décharge une extension.

[!NOTE] This API cannot be called before the ready event of the app module is emitted.

Deprecated: Use the new ses.extensions.removeExtension API.

ses.getExtension(extensionId) __ obsolète

• extensionId string - ID de l'extension demandée

Retourne Extension | null | - L'extension chargée ayant l'ID donné.

[!NOTE] This API cannot be called before the ready event of the app module is emitted.

Deprecated: Use the new ses.extensions.getExtension API.

ses.getAllExtensions() __ obsolète

Retourne Extension[] - Une liste de toutes les extensions chargées.

[!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()

Retourne string | null - Chemin absolu du système de fichiers où les données pour cette session sont enregistrées sur le disque. Retourne null dans le cas des sessions en mémoire.

ses.clearData([options])

• options Object (facultatif)
  • dataTypes String[] (optional) - The types of data to clear. By default, this will clear all types of data. This can potentially include data types not explicitly listed here. (See Chromium's BrowsingDataRemover for the full list.)
    • backgroundFetch - Background Fetch
    • cache - Cache (comprend cachestorage et shadercache)
    • cookies - Cookies
    • downloads - Téléchargements
    • fileSystems - Systèmes de fichiers
    • indexedDB - IndexedDB
    • localStorage - Local Storage
    • serviceWorkers - Service Workers
    • webSQL - WebSQL
  • origins String[] (optional) - Clear data for only these origins. Cannot be used with excludeOrigins.
  • excludeOrigins String[] (optional) - Clear data for all origins except these ones. Cannot be used with origins.
  • avoidClosingConnections boolean (optional) - Skips deleting cookies that would close current network connections. (Default: false)
  • originMatchingMode String (optional) - The behavior for matching data to origins.
    • third-parties-included (default) - Storage is matched on origin in first-party contexts and top-level-site in third-party contexts.
    • origin-in-all-contexts - Storage is matched on origin only in all contexts.

Returns Promise<void> - resolves when all data has been cleared.

Clears various different types of data.

This method clears more types of data and is more thorough than the clearStorageData method.

[!NOTE] Cookies are stored at a broader scope than origins. When removing cookies and filtering by origins (or excludeOrigins), the cookies will be removed at the registrable domain level. For example, clearing cookies for the origin https://really.specific.origin.example.com/ will end up clearing all cookies for example.com. Clearing cookies for the origin https://my.website.example.co.uk/ will end up clearing all cookies for example.co.uk.

[!NOTE] Clearing cache data will also clear the shared dictionary cache. This means that any dictionaries used for compression may be reloaded after clearing the cache. If you wish to clear the shared dictionary cache but leave other cached data intact, you may want to use the clearSharedDictionaryCache method.

For more information, refer to Chromium's BrowsingDataRemover interface.

Propriétés d'instance

Les propriétés suivantes sont disponibles pour les instances de Session :

ses.availableSpellCheckerLanguages Readonly

Tableau de string[] se composant de tous les langages connus du correcteur orthographique disponible. Une erreur surviendra si un code de langue absent de ce tableau est fournit à l'API setSpellCheckerLanguages.

ses.spellCheckerEnabled

boolean indique si le correcteur orthographique interne est activé.

ses.storagePath Readonly

string | null indique le chemin absolu du système de fichiers où les données pour cette session sont enregistrées ur le disque. Retourne null dans le cas des sessions en mémoire.

ses.cookies Readonly

A Cookies object for this session.

ses.extensions Lecture seule

A Extensions object for this session.

ses.serviceWorkers Readonly

A ServiceWorkers object for this session.

ses.webRequest Readonly

A WebRequest object for this session.

ses.protocol Readonly

A Protocol object for this session.

const { app, session } = require('electron')
const path = require('node:path')

app.whenReady().then(() => {
  const protocol = session.fromPartition('some-partition').protocol
  if (!protocol.registerFileProtocol('atom', (request, callback) => {
    const url = request.url.substr(7)
    callback({ path: path.normalize(path.join(__dirname, url)) })
  })) {
    console.error('Failed to register protocol')
  }
})

ses.netLog Readonly

A NetLog object for this session.

const { app, session } = require('electron')

app.whenReady().then(async () => {
  const netLog = session.fromPartition('some-partition').netLog
  netLog.startLogging('/path/to/net-log')
  // After some network events
  const path = await netLog.stopLogging()
  console.log('Net-logs written to', path)
})