Classe : WebRequest

Intercepte et modifie le contenu d'une requête à différents stades de son existence.

Processus : Principal
Cette classe n'est pas exportée depuis le module 'electron'. Elle n'est disponible qu'en tant que valeur de retour des autres méthodes dans l'API Electron.

Les instances de la classe WebRequest sont accessibles à l'aide de la propriété WebRequest d'une Session.

Les méthodes de WebRequest peuvent de manière facultative recevoir un filter et un listener. Le listener va être appelé par listener(details) quand l'événement de l'API est émis. L'objet details représente la requête.

⚠️ Seul le dernier listener associé sera utilisé. Le passage de null en tant que listener annulera l'abonnement à l'événement.

L'objet filter possède une propriété url qui est un tableau de modèles d'URL qui seront utilisés pour filtrer les requêtes qui ne satisfont pas aux modèles. Si filter est omis, toutes les requêtes seront jugées comme conformes.

Pour certains événements, le listener est passé accompagné d'une callback, qui doit appelée avec un objet responselorsque le listener a fini son travail.

Exemple d'ajout de l'en-tête User-Agent pour les requêtes :

const { session } = require('electron')

// Modifie le user agent pour toutes les requêtes concernant les url indiquées.
const filter = {
  urls: ['https://*.github.com/*', '*://electron.github.io/*']
}

session.defaultSession.webRequest.onBeforeSendHeaders(filter, (details, callback) => {
  details.requestHeaders['User-Agent'] = 'MyAgent'
  callback({ requestHeaders: details.requestHeaders })
})

Méthodes d’instance

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

`webRequest.onBeforeRequest([filter, ]listener)`

filter WebRequestFilter (facultatif)
listener Function | null
- Objet details
  - id Integer
  - url string
  - method string
  - webContentsId Integer (facultatif)
  - webContents WebContents (facultatif)
  - frame WebFrameMain (facultatif)
  - resourceType string - Peut prendre une des valeurs suivantes mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket ou other.
  - referrer string
  - timestamp Double
  - uploadData UploadData[]
- callback Function
  - Objet response
    - cancel boolean)
    - redirectURL string (facultatif) - Empêche la requête originale d'être envoyée ou complétée, à la place, celle ci est redirigée vers l'URL donnée.

Le listener sera appelé par listener(details, callback) lorsqu'une requête est sur le point de se produire.

uploadData est un tableau d'objets UploadData.

La callback doit être appelé avec un objet response.

Exemples d'urls valides :

'http://foo:1234/'
'http://foo.com/'
'http://foo:1234/bar'
'*://*/*'
'*://example.com/*'
'*://example.com/foo/*'
'http://*.foo:1234/'
'file://foo:1234/bar'
'http://foo:*/'
'*://www.foo.com/'

`webRequest.onBeforeSendHeaders([filter, ]listener)`

filter WebRequestFilter (facultatif)
listener Function | null
- Objet details
  - id Integer
  - url string
  - method string
  - webContentsId Integer (facultatif)
  - webContents WebContents (facultatif)
  - frame WebFrameMain (facultatif)
  - resourceType string - Peut prendre une des valeurs suivantes mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket ou other.
  - referrer string
  - timestamp Double
  - uploadData UploadData[] (facultatif)
  - requestHeaders Record<string, string\>
- callback Function
  - Objet beforeSendResponse
    - cancel boolean)
    - requestHeaders Record<string, string | string[]\> (optional) - When provided, request will be made with these headers.

Le listener sera appelé par listener(details, callback) avant d’envoyer une requête HTTP, et une fois que les en-têtes de requête sont disponibles. Cela peut se produire après une connexion TCP au serveur, mais avant que des données http ne soient envoyées.

La callback doit être appelée avec un objet response.

`webRequest.onSendHeaders([filter, ]listener)`

filter WebRequestFilter (facultatif)
listener Function | null
- Objet details
  - id Integer
  - url string
  - method string
  - webContentsId Integer (facultatif)
  - webContents WebContents (facultatif)
  - frame WebFrameMain (facultatif)
  - resourceType string - Peut prendre une des valeurs suivantes mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket ou other.
  - referrer string
  - timestamp Double
  - requestHeaders Record<string, string\>

Le listener sera appelé par listener(details) juste avant qu'une requête ne soit envoyée au serveur, les modifications de la réponse onBeforeSendHeaders précédente sont visibles au moment où l'écouteur est déclenché.

`webRequest.onHeadersReceived([filter, ]listener)`

filter WebRequestFilter (facultatif)
listener Function | null
- Objet details
  - id Integer
  - url string
  - method string
  - webContentsId Integer (facultatif)
  - webContents WebContents (facultatif)
  - frame WebFrameMain (facultatif)
  - resourceType string - Peut prendre une des valeurs suivantes mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket ou other.
  - referrer string
  - timestamp Double
  - statusLine string
  - statusCode Integer
  - responseHeaders Record<string, string[]\> (optional)
- callback Function
  - Objet headersReceivedResponse
    - cancel boolean)
    - responseHeaders Record<string, string | string[]\> (optional) - When provided, the server is assumed to have responded with these headers.
    - statusLine string (optionelle) - Doit être fourni lorsque vous remplacez responseHeaders pour changer le statut de l'en-tête sinon le statut de l'en-tête de la réponse originale sera utilisé.

Le listener sera appelé par listener(details, callback) à la réception des en-têtes de réponse HTTP de la requête.

La callback doit être appelée avec un objet response.

`webRequest.onResponseStarted([filter, ]listener)`

filter WebRequestFilter (facultatif)
listener Function | null
- Objet details
  - id Integer
  - url string
  - method string
  - webContentsId Integer (facultatif)
  - webContents WebContents (facultatif)
  - frame WebFrameMain (facultatif)
  - resourceType string - Peut prendre une des valeurs suivantes mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket ou other.
  - referrer string
  - timestamp Double
  - responseHeaders Record<string, string[]\> (optional)
  - fromCache booléen - Indique si la réponse a été extraite du cache disque.
  - statusCode Integer
  - statusLine string

Le listener sera appelé par listener(details) lors de la réception du premier octet de la réponse. Pour les requêtes HTTP, cela signifie que la ligne de statut et les en-têtes de réponse sont disponibles.

`webRequest.onBeforeRedirect([filter, ]listener)`

filter WebRequestFilter (facultatif)
listener Function | null
- Objet details
  - id Integer
  - url string
  - method string
  - webContentsId Integer (facultatif)
  - webContents WebContents (facultatif)
  - frame WebFrameMain (facultatif)
  - resourceType string - Peut prendre une des valeurs suivantes mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket ou other.
  - referrer string
  - timestamp Double
  - redirectURL string
  - statusCode Integer
  - statusLine string
  - ip string (optionelle) - L'adresse IP du serveur à laquelle la requête a été effectivement envoyée.
  - fromCache boolean
  - responseHeaders Record<string, string[]\> (optional)

Le listener sera appelé par listener(details) lorsqu'une redirection initiée par le serveur va se produire.

`webRequest.onCompleted([filter, ]listener)`

filter WebRequestFilter (facultatif)
listener Function | null
- Objet details
  - id Integer
  - url string
  - method string
  - webContentsId Integer (facultatif)
  - webContents WebContents (facultatif)
  - frame WebFrameMain (facultatif)
  - resourceType string - Peut prendre une des valeurs suivantes mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket ou other.
  - referrer string
  - timestamp Double
  - responseHeaders Record<string, string[]\> (optional)
  - fromCache boolean
  - statusCode Integer
  - statusLine string
  - error string

Le listener sera exécuté par listener(details) lorsqu'une requète est complétée.

`webRequest.onErrorOccurred([filter, ]listener)`

filter WebRequestFilter (facultatif)
listener Function | null
- Objet details
  - id Integer
  - url string
  - method string
  - webContentsId Integer (facultatif)
  - webContents WebContents (facultatif)
  - frame WebFrameMain (facultatif)
  - resourceType string - Peut prendre une des valeurs suivantes mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket ou other.
  - referrer string
  - timestamp Double
  - fromCache boolean
  - error string - La description de l'erreur.

Le listener sera appelé par listener(details) lorsqu'une erreur se produit.