Aller au contenu principal

webContents

Gère les pages web et leur rendu.

Processus : Main

webContents est un EventEmitter. Il est responsable du rendu et du contrôle d'une page web et est une propriété de l'objet BrowserWindow. Exemple d'accès à l'objet webContents :

const { BrowserWindow } = require('electron')

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

const contents = win.webContents
console.log(contents)

Méthodes​

Ces méthodes sont accessibles depuis le module webContents :

const { webContents } = require('electron')
console.log(webContents)

webContents.getAllWebContents()​

Retourne WebContents[] - Un tableau de toutes les instances de WebContents. Celui-ci contiendra les webContents de toutes les fenêtres, webviews, devtools ouvertes et pages d'extention d'arrière-plan des devtools .

webContents.getFocusedWebContents()​

Retourne WebContents | null - Le contenu web qui a le focus dans cette application, sinon retourne null.

webContents.fromId(id)​

  • id Integer

Retourne WebContents | undefined - L'instance de WebContents dont l'ID est donné, ou undefined s'il n'y a pas de WebContents associés à cet ID.

webContents.fromFrame(frame)​

  • frame WebFrameMain

Retourne WebContents | undefined - une instance de WebContents avec le TargetID donné, ou bien undefined lorsqu'il n'y a aucun WebContents associé avec le TargetID donné.

webContents.fromDevToolsTargetId(targetId)​

  • targetId string - Le protocole Chrome DevTools TargetID associé à l'instance WebContents.

Retourne WebContents | undefined - Une instance WebContents avec le TargetID donné, ou undefined s'il n'y a pas de WebContents associés avec le TargetID donné.

Lors de la communication avec le protocole Chrome DevTools, il peut être utile de rechercher une instance WebContents par le TargetID qui lui est assigné.

async function lookupTargetId (browserWindow) {
  const wc = browserWindow.webContents
  await wc.debugger.attach('1.3')
  const { targetInfo } = await wc.debugger.sendCommand('Target.getTargetInfo')
  const { targetId } = targetInfo
  const targetWebContents = await webContents.fromDevToolsTargetId(targetId)
}

Classe : WebContents​

Affiche et contrôle le contenu d'une instance de BrowserWindow.

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.

Événements d’instance​

Événement : 'did-finish-load'​

Émis lorsque la navigation a abouti, c'est à dire que le loader de l'onglet a cessé de tourner, et que l'événement onload a été émis.

Événement : 'did-fail-load'​

Retourne :

  • event Event
  • errorCode Integer
  • errorDescription string
  • validatedURL string
  • isMainFrame boolean
  • frameProcessId Integer
  • frameRoutingId Integer

Cet événement est comme did-finish-load mais émis lorsque le chargement a échoué. La liste complète des codes d'erreur et leur signification est disponible ici.

Événement : 'did-fail-provisional-load'​

Retourne :

  • event Event
  • errorCode Integer
  • errorDescription string
  • validatedURL string
  • isMainFrame boolean
  • frameProcessId Integer
  • frameRoutingId Integer

Cet événement est comme did-fail-load mais émis lorsque la chargement a été annulé (par exemple par un appel à window.stop()).

Événement : 'did-frame-finish-load'​

Retourne :

  • event Event
  • isMainFrame boolean
  • frameProcessId Integer
  • frameRoutingId Integer

Émis lorsqu'un frame a fini sa navigation.

Événement : 'did-start-loading'​

Correspond au moment où le loader de l'onglet commence à tourner.

Événement : 'did-stop-loading'​

Correspond au moment où le loader de l'onglet arrête de tourner.

Événement : 'dom-ready'​

Émis lorsque le document de la frame de plus haut niveau est chargé.

Événement : 'page-title-updated'​

Retourne :

  • event Event
  • title string
  • explicitSet boolean

Emis lorsque le titre de la page est défini pendant la navigation. explicitSet est à false lorsque le titre est synthétisé à partir de l’url du fichier.

Événement : 'page-favicon-updated'​

Retourne :

  • event Event
  • favicons string[] - Tableau d'URLs.

Émis lorsque la page reçoit l’url du favicon.

Événement : 'content-bounds-updated'​

Retourne :

  • event Event
  • bounds Rectangle - nouvelles limites de contenu demandées

Émis lorsque la page appelle window.moveTo, window.resizeTo ou par les API associées.

Par défaut, cela déplacera la fenêtre. Pour prévenir ce comportement, appelez event.preventDefault().

Événement : 'did-create-window'​

Retourne :

  • window BrowserWindow
  • Objet details
    • url string - l'URL de la fenêtre crée.
    • frameName string - Nom donné à la fenêtre crée lors de l'appel à window.open().
    • options BrowserWindowConstructorOptions - Options utilisées pour créer la BrowserWindow. Elles sont fusionnées par ordre de priorité croissante : options analysées à partir de la chaîne features de window.open(), webPreferences liées à la sécurité héritées du parent et enfin, les options données par webContents.setWindowOpenHandler. Les options non reconnues ne sont pas filtrées.
    • referrer Referrer - L'origine qui sera passée à la nouvelle fenêtre. Peut selon la politique du référent entraîner ou non l'envoi de l'en-tête Referer .
    • postBody PostBody (facultatif) - Les données qui seront envoyées à la nouvelle fenêtre, ainsi que les en-têtes appropriés qui seront définis. Si aucune donnée ne doit être envoyée, la valeur sera null. Est uniquement défini lorsque la fenêtre est créée par un formulaire définissant target=_blank.
    • disposition string - Peut prendres les valeurs default, foreground-tab, background-tab, new-window, save-to-disk et other.

Émis suite à la création réussie d’une fenêtre via window.open dans le moteur de rendu. Non émis si la création de la fenêtre est annulée à partir de webContents.setWindowOpenHandler.

Voir window.open() pour plus de détails et l'utilisation en conjonction avec webContents.setWindowOpenHandler.

Événement : 'will-navigate'​

Retourne :

  • event Event
  • url string

Émis lorsqu’un utilisateur ou la page souhaite démarrer la navigation. Cela peut se produire lorsque l’objet window.location est modifié ou qu’un utilisateur clique sur un lien dans la page.

Cet événement ne sera pas émis lorsque la navigation démarre par programmation à l'aide d'APIs telles que webContents.loadURL ou webContents.back.

Il n’est pas non plus émis pour les navigations internes à la page, telles que le clic sur les liens d’ancrage ou la mise à jour du window.location.hash. Utiliser l'événement did-navigate-in-page pour cela.

Appeler event.preventDefault() permet d'éviter la navigation.

Événement : 'did-start-navigation'​

Retourne :

  • event Event
  • url string
  • isInPlace boolean
  • isMainFrame boolean
  • frameProcessId Integer
  • frameRoutingId Integer

Émis lorsqu’une frame (y compris principale) commence à naviguer. isInPlace sera true pour les navigations internes à la page.

Événement : 'will-redirect'​

Retourne :

  • event Event
  • url string
  • isInPlace boolean
  • isMainFrame boolean
  • frameProcessId Integer
  • frameRoutingId Integer

Émis lorsqu’une redirection côté serveur se produit pendant la navigation. Par exemple, une redirection 302 .

Cet événement sera émis après did-start-navigation et pour la même navigation toujours avant l'événement did-redirect-navigation .

L'appel à event.preventDefault() empêchera la navigation (pas seulement la redirection).

Événement : 'did-start-navigation'​

Retourne :

  • event Event
  • url string
  • isInPlace boolean
  • isMainFrame boolean
  • frameProcessId Integer
  • frameRoutingId Integer

Émis après une redirection côté serveur pendant la navigation. Par exemple, une redirection 302 .

On ne peut pas éviter cet événement et si vous souhaitez empêcher les redirections, vous devez supprimer l’événement will-redirect ci-dessus.

Événement : 'did-navigate'​

Retourne :

  • event Event
  • url string
  • httpResponseCode Integer - -1 fpour les navigations non HTTP
  • httpStatusText string - vide pour les navigations non HTTP

Émis lorsque la navigation d'une fenêtre principale est terminée.

Cet événement n’est pas émis pour les navigations internes à la page, telles que le clic sur les liens d’ancrage ou la mise à jour du window.location.hash. Utiliser l'événement did-navigate-in-page pour cela.

Événement : 'did-navigate'​

Retourne :

  • event Event
  • url string
  • httpResponseCode Integer - -1 fpour les navigations non HTTP
  • httpStatusText string - vide pour les navigations non HTTP,
  • isMainFrame boolean
  • frameProcessId Integer
  • frameRoutingId Integer

Émis lorsqu'une navigation est terminée.

Cet événement n’est pas émis pour les navigations internes à la page, telles que le clic sur les liens d’ancrage ou la mise à jour du window.location.hash. Utiliser l'événement did-navigate-in-page pour cela.

Événement : 'did-navigate-in-page'​

Retourne :

  • event Event
  • url string
  • isMainFrame boolean
  • frameProcessId Integer
  • frameRoutingId Integer

Émis lors d'une navigation interne à la page et dans n’importe quelle frame.

En cas de navigation dans la page, l'URL de la page change mais ne provoque pas de navigation à l'extérieur de la page. Par exemple, lorsque vous cliquez sur un lien d'ancrage ou lorsque l'événement DOM hashchange est déclenché.

Événement : 'will-prevent-unload'​

Retourne :

  • event Event

Émis lorsqu’un écouteur de l'événement beforeunload tente d’annuler un déchargement de la page.

Appeler event.preventDefault() ignorera l'écouteur de l'événement beforeunload et va laisser la page se décharger.

const { BrowserWindow, dialog } = require('electron')
const win = new BrowserWindow({ width: 800, height: 600 })
win.webContents.on('will-prevent-unload', (event) => {
  const choice = dialog.showMessageBoxSync(win, {
    type: 'question',
    buttons: ['Leave', 'Stay'],
    title: 'Do you want to leave this site?',
    message: 'Changes you made may not be saved.',
    defaultId: 0,
    cancelId: 1
  })
  const leave = (choice === 0)
  if (leave) {
    event.preventDefault()
  }
})

Remarque: Cela sera émis pour lesBrowserViews mais ne sera pas respecté - c’est parce que nous avons choisi de ne pas lier le cycle de vie de la BrowserView à sa BrowserWindow propriétaire même s’il en existe une selon la spécification .

Événement : 'crash' Déprécié​

Retourne :

  • event Event
  • killed boolean

Émis lorsque le processus renderer crash ou est interrompu.

Deprecated: Cet événement est remplacé par l'événement render-process-gone qui contient plus d'informations sur la raison de la disparition du processus enfant. Ceci n'est pas toujours causé par un plantage. Le booléen killed peut être remplacé par la vérification de reason === 'killed' lorsque vous passez à l'utilisation de cet événement.

Événement : 'render-process-gone'​

Retourne :

  • event Event
  • Objet details
    • reason string - Raison pour laquelle le processus de rendu a disparu. Valeurs possibles :
      • clean-exit - Le Processus s'est terminé avec le code de sortie zéro
      • abnormal-exit - Le Processus s'est terminé avec un code de sortie différent de zéro
      • killed - Le processus a reçu un SIGTERM ou a été tué autrement de l'extérieur
      • crashed - Processus s'est planté
      • oom - Le processus est tombé à cours de mémoire
      • launch-failed - Le processus n'a pu se lancer avec succès
      • integrity-failure - Les vérifications d'intégrité du code Windows ont échouées
    • exitCode Integer - Le code de sortie du processus, sauf si reason est launch-failed, dans ce cas là, exitCode sera le code d'échec du lancement specifique à la plateforme.

Émis lorsque le processus de rendu disparait de manière inattendue. C'est habituelement parce qu'il s'est planté ou qu'il a été tué.

Événement : 'unresponsive'​

Émis lorsque la page web cesse de répondre.

Événement : 'responsive'​

Émis lorsque la page web répond à nouveau.

Événement : 'plugin-crashed'​

Retourne :

  • event Event
  • name string
  • version string

Émis lorsqu’un processus de plugin crash.

Événement : 'destroyed'​

Émis lorsqu'un webContents est détruit.

Événement : 'before-input-event'​

Retourne :

Émis lorsqu'un événement d'entrée est envoyé au WebContents. Voir InputEvent pour plus de détails.

Événement : 'before-input-event'​

Retourne :

Émis avant d'envoyer les événements keydown et keyup dans la page. Appeler event.preventDefault empêchera les événements keydown/keyup et les raccourcis du menu dans la page.

Pour empêcher uniquement les raccourcis de menu, utilisez setIgnoreMenuShortcuts:

const { BrowserWindow } = require('electron')

const win = new BrowserWindow({ width: 800, height: 600 })

win.webContents.on('before-input-event', (event, input) => {
  // Par exemple, active seulement les raccourcis clavier vers le menu de l'application
  // lorsque les touches Ctrl/Cmd sont enfoncées.
  win.webContents.setIgnoreMenuShortcuts(!input.control && !input.meta)
})

Événement : 'enter-html-full-screen'​

Émis lorsque la fenêtre entre dans un état de plein écran déclenchée par l’API HTML.

Événement : 'leave-html-full-screen'​

Émis lorsque la fenêtre revient d'un état de plein écran déclenchée par l’API HTML.

Événement : 'zoom-changed'​

Retourne :

  • event Event
  • zoomDirection string - Peut être in ou out.

Émis lorsque l'utilisateur demande à changer le niveau de zoom en utilisant la molette de la souris.

Événement : 'blur'​

Émis lorsque le WebContents perd le focus.

Événement : 'focus'​

Émis lorsque le WebContents acquiert le focus.

Notez que sur macOS, le fait d’avoir le focus signifie que le WebContents est le premier intervenant de la fenêtre, de sorte que le basculement du focus entre les fenêtres ne déclenche pas les événements focus et blur de WebContents, car le premier intervenant de chaque fenêtre n’est pas modifié.

Les événements focus et blur de WebContents ne doivent être utilisés que pour détecter changement de focus entre différents WebContents et BrowserView dans la même fenêtre. .

Événement : 'devtools-opened'​

Émis lorsque la DevTools est ouverte.

Événement : 'devtools-closed'​

Émis lorsque la DevTools est fermée.

Événement : 'devtools-focused'​

Émis lorsque la DevTools est active / ouverte.

Événement 'certificate-error'​

Retourne :

  • event Event
  • url string
  • error string - Le code d'erreur.
  • certificate Certificate
  • callback Function
    • isTrusted boolean - Indique si le certificat peut être considéré comme fiable.
  • isMainFrame boolean

Émis lorsqu'il n'a pas pu vérifier le certificat de l'url.

L'utilisation est pareil que l'événement certificate-error de app.

Événement : 'select-client-certificate'​

Retourne :

  • event Event
  • url URL
  • certificateList Certificate[]
  • callback Function
    • certificate Certificate - Doit être un certificat dans la liste donnée.

Émis lorsqu'un certificat client est demandé.

L'utilisation est pareil que l'événement select-client-certificate de app.

Événement : 'login'​

Retourne :

  • event Event
  • Objet authenticationResponseDetails
    • url URL
  • Objet authInfo
    • isProxy boolean
    • scheme string
    • host string
    • port Integer
    • realm string
  • callback Function
    • username string (facultatif)
    • password string (facultatif)

Émis lorsque webContents veut faire une authentification normale.

L'utilisation est pareil que l'événement login de app.

Événement : 'found-in-page'​

Retourne :

  • event Event
  • result Object
    • requestId Integer
    • activeMatchOrdinal Integer - Position du résultat actif.
    • matches Integer - Nombre de résultats.
    • sélectionArea Rectangle - Coordonnées de la région de la première correspondance.
    • finalUpdate boolean

Émis lorsqu'un résultat est disponible pour la requête [webContents.findInPage].

Événement : 'media-started-playing'​

Émis lorsqu'un média se démarre.

Événement : 'media-paused'​

Émis lorsque le média est suspendu ou terminé.

Événement : 'did-change-theme-color'​

Retourne :

  • event Event
  • color (string | null) - La couleur du thème est au format '#rrggbb'. Il est null lorsqu’aucune couleur de thème n’est définie.

Émis lorsque la couleur du thème d'une page change. Cela est généralement dû à la rencontre d'une balise meta :

<meta name='theme-color' content='#ff0000'>

Événement : 'update-target-url'​

Retourne :

  • event Event
  • url string

Émis lorsque la souris passe sur un lien ou que le clavier déplace le focus vers un lien.

Événement : 'cursor-changed'​

Retourne :

  • event Event
  • type string
  • image NativeImage (facultatif)
  • scale Float (facultatif) - Facteur de mise à l'échelle pour le curseur personnalisé.
  • size Size (facultatif) - La taille de l'image.
  • hotspot Point (facultatif) - Coordonnées du point actif du curseur personnalisé.

Émis lorsque le type du curseur change. Le paramètre type peut prendre les valeurs suivantes default, crosshair, pointer, text, wait, help, e-resize, n-resize, ne-resize, nw-resize, s-resize, se-resize, sw-resize, w-resize, ns-resize, ew-resize, nesw-resize, nwse-resize, col-resize, row-resize, m-panning, e-panning, n-panning, ne-panning, nw-panning, s-panning, se-panning, sw-panning, w-panning, move, vertical-text, cell, context-menu, alias, progress, nodrop, copy, none, not-allowed, zoom-in, zoom-out, grab, grabbing ou custom.

Si la valeur du paramètre type est custom, le paramètre image contiendra l'image du curseur personnalisé dans une NativeImage, et d'autre part scale, size et hotspot contiendront les informations complémentaires à propos du curseur personnalisé.

Événement : 'context-menu'​

Retourne :

  • event Event
  • params Object
    • x Integer - coordonnée x.
    • y Integer - coordonée y.
    • frame WebFrameMain - Frame à partir de laquelle le menu contextuel a été appelé.
    • linkURL string - L'URL du lien qui englobe le nœud du menu contextuel.
    • linkText string - Texte associé au lien. Peut être une chaîne vide si le contenu du lien est une image.
    • pageURL string - L'URL de la page haut niveau d'où le menu contextuel a été invoqué.
    • frameURL string - L'URL de la subframe d'où le menu contextuel a été invoqué.
    • chaîne srcURL : URL de la source de l’élément par lequel le menu contextuel a été appelé. Les éléments avec des URL sources peuvent être des images, de l’audio ou de la vidéo.
    • mediaType string - Type du nœud sur lequel le menu contextuel a été appelé. Peut prendre une des valeurs suivantes: none, image, audio, video, canvas, file ou plugin.
    • hasImageContents boolean - Si le menu contextuel a été invoqué sur une image au contenu non-vide ou non.
    • isEditable boolean - Si le contexte est modifiable ou non.
    • selectionText string - Texte de la sélection sur laquelle le menu contextuel a été invoqué.
    • titleText string : Texte du title de la sélection à partir de laquelle le menu contextuel a été appelé.
    • altText string - Texte de remplacement (alt) de la sélection à partir de laquelle le menu contextuel a été appelé.
    • chaîne suggestedFilename - Nom de fichier suggéré à utiliser lors de l’enregistrement du fichier via l’option « Enregistrer le lien sous » du menu contextuel.
    • selectionRect Rectangle - Rectangle représentant les coordonnées de la sélection dans l’espace du document .
    • selectionStartOffset number- Position de départ du texte de la sélection.
    • referrerPolicy Referrer - Stratégie du réferrer de la frame à partir de laquelle le menu est appelé.
    • misspelledWord string - Mot mal orthographié sous le curseur, si applicable.
    • dictionarySuggestions string[] - Un tableau de mots suggérés à montrer à l'utilisateur pour remplacer le misspelledWord. Uniquement disponible si un mot est mal orthographié et que le correcteur orthographique est activé.
    • frameCharset string - L'encodage des caractères de la fenêtre sur lequel le menu a été appelé.
    • inputFieldType string - Si le menu contextuel a été appelé sur un champ modifiable, donne le type de ce champ. Les valeurs possibles sont none, plainText, password, other.
    • spellcheckEnabled boolean - Indique si la vérification orthographique est activée ou non dans les cas où le contexte est éditable,.
    • menuSourceType string - Source de l'appel au menu contextuel. Peut être une de ces valeurs none, mouse, keyboard, touch, touchMenu, longPress, longTap, touchHandle, stylus, adjustSelection, adjustSelectionReset.
    • mediaFlags Object - Les drapeaux de l'élément multimédia sur lequel le menu contextuel a été appelé .
      • inError boolean - Si l'élément multimédia a crash.
      • isPaused boolean - Si l'élément multimédia est en pause.
      • isMuted boolean - Si l'élément multimédia est mis en sourdine.
      • hasAudio boolean - Si l'élément multimédia émet un son audio.
      • isLooping boolean - Si l'élément multimédia est en boucle.
      • isControlsVisible boolean - Si les contrôles de l'élément multimédia sont visibles.
      • canToggleControls boolean - Si les contrôles de l'élément multimédia sont toggleable.
      • canPrint booléen - Indique si on peut faire une impression à partir de l'élément multimédia.
      • canSave booléen - Indique si l'élément multimédia peut être téléchargé ou non.
      • canShowPictureInPicture boolean - Indique si l'élément multimédia peut s'afficher en mode "picture-in-picture".
      • isShowingPictureInPicture booléen - Indique si l'élément multimédia est actuellement affiché en mode "picture-in-picture".
      • canRotate boolean - Si l'élément multimédia peut être pivoté.
      • canLoop booléen - Indique si l'élément multimédia peut être mis en mode boucle.
    • editFlags Object - Ces drapeaux indiquent si le moteur de rendu estime être en mesure d'effectuer l'action correspondante.
      • canUndo boolean - Si le moteur de rendu pense pouvoir aller en arrière.
      • canRedo boolean - Si le moteur de rendu pense pouvoir aller en avant.
      • canCut boolean - Si le moteur de rendu pense pouvoir couper.
      • canCopy boolean - Si le moteur de rendu pense pouvoir copier.
      • canPaste boolean - Si le moteur de rendu pense pouvoir coller.
      • canDelete boolean - Si le moteur de rendu pense pouvoir supprimer.
      • canSelectAll boolean - Si le moteur de rendu pense pouvoir tout sélectionner.
      • canEditRichly boolean - Indique si le moteur de rendu pense pouvoir editer du texte avec des styles.

Émis lorsqu'un nouveau menu contextuel doit être géré.

Événement : 'select-bluetooth-device'​

Retourne :

Émis lorsqu’un périphérique bluetooth doit être sélectionné lors d’un appel à navigator.bluetooth.requestDevice. callback doit être appelé avec le deviceId du dispositif à sélectionner. Le passage d'une chaîne vide à la callback annulera la demande.

Si aucun écouteur d’événement na été ajouté pour cet événement, ou si event.preventDefault n’est pas appelé lors du traitement de cet événement, le premier appareil disponible sera sélectionné automatiquement.

En raison de la nature de bluetooth, l'exploration des appareils lorsque navigator.bluetooth.requestDevice est appelée peut prendre du temps et causer l'émission de plusieurs select-bluetooth-device avant que callback ne soit appelé avec un identifiant de périphérique ou une chaîne vide pour annuler la requête.

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

let win = null

app.whenReady().then() => {
  win = new BrowserWindow({ width: 800, height: 600 })
  win.webContents.on('select-bluetooth-device', (event, deviceList, callback) => {
    event.preventDefault()
    const result = deviceList.find((device) => {
      retour device.deviceName ==='test'
    })
    si (!result) {
      // L’appareil n’a pas été trouvé, nous devons donc attendre (eg jusqu'à
      // ce que l’appareil soit activé) ou annuler la demande en appelant la callback
      // avec une chaîne vide.
      callback('')
    } else {
      callback(result.deviceId)
    }
  })
})

Événement : 'paint'​

Retourne :

Émis lorsqu’une nouvelle frame est générée. Seule la zone devant être mise à jour est passée dans le buffer .

const { BrowserWindow } = require('electron')

const win = new BrowserWindow({ webPreferences: { offscreen: true } })
win.webContents.on('paint', (event, dirty, image) => {
  // updateBitmap(dirty, image.getBitmap())
})
win.loadURL('http://github.com')

Événement : 'devtools-reload-page'​

Émis quand la fenêtre des outils développeur demande aux webContents de se recharger

Événement : 'will-attach-webview'​

Retourne :

  • event Event
  • webPreferences WebPreferences - Les préférences web qui seront utilisées par la page hébergeant la webview. . Cet objet peut être modifié pour ajuster les préférences de la page hôte .
  • params Record<string, string> - Les autres paramètres de la <webview> tel que l'URL src. Cet objet peut être modifié pour ajuster les préférences de la page hôte .

Émis lorsque le contenu web d'une <webview>est attaché à ce webContents. L'appel à event.preventDefault() détruira la page hôte.

Cet événement peut être utilisé pour configurer les webPreferences des webContents d'une <webview> avant son chargement, et fournit la possibilité de définir des paramètres qui ne peuvent pas être définis via les attributs d'une <webview>.

Événement : 'will-attach-webview'​

Retourne :

  • event Event
  • webContents WebContents - Les contenus web invités qui sont utilisés par <webview>.

Émis quand un <webview> a été rattaché à ce contenu web.

Événement : 'console-message'​

Retourne :

  • event Event
  • level Integer - Le niveau de logging, de 0 à 3. Correspondant dans l'ordre croissant à verbose, info, warning et error.
  • message string - Message actuel de la console
  • line Integer - Numéro de la ligne du source qui a déclenché le message affiché dans la console
  • sourceId string

Émis lorsque la fenêtre associée affiche un message de log dans la console.

Événement : 'preload-error'​

Retourne :

  • event Event
  • preloadPath string
  • error Error

Émis lorsque le script de préchargement preloadPath lance une exception non gérée error.

Événement : 'ipc-message'​

Retourne :

  • event Event
  • channel string
  • ...args any[]

Émis lorsque le processus de rendu envoie un message asynchrone via ipcRenderer.send().

Voir aussi webContents.ipc, qui fournit une interface similaire à IpcMain pour répondre aux messages IPC spécifiques à ce WebContents.

Événement : 'ipc-message'​

Retourne :

  • event Event
  • channel string
  • ...args any[]

Émis lorsque le processus de rendu envoie un message synchrone via ipcRenderer.sendSync().

Voir aussi webContents.ipc, qui fournit une interface similaire à IpcMain pour répondre aux messages IPC spécifiques à ce WebContents.

Événement : 'preferred-size-changed'​

Retourne :

  • event Event
  • preferredSize Size - Taille minimale requise pour contenir la structure du document — sans avoir besoin de faire défiler.

Émis lorsque la taille préférée du WebContents a changé.

Cet événement ne sera émis que lorsque enablePreferredSizeMode est défini à true dans webPreferences.

Évènement : 'session-created'​

Retourne :

  • event Event
  • Objet details
    • frame WebFrameMain

Émis lorsque la mainFrame, <iframe>, ou <iframe> imbriquée, est chargée dans la page.

Méthodes d’instance​

contents.loadURL(url[, options])​

  • url string
  • options Object (facultatif)
    • httpReferrer (string | Referrer) (facultatif) - L'url HTTP d'un Referrer.
    • userAgent string (optionnel) - L'agent utilisateur à l'origine de la requête.
    • extraHeaders string (optionnel) - Headers supplémentaires séparés par "\n".
    • postData (UploadRawData | UploadFile)[] (facultatif)
    • baseURLForDataURL string (facultatif) - Url de base (avec le séparateur de fin du chemin) pour que les fichiers soient chargés par l'Url transmise. Ceci n'est nécessaire que si l'url spécifiée est une Url de données et a besoin de charger d'autres fichiers.

Retourne Promise<void> - la promesse se résoudra lorsque la page aura terminé le chargement (voir did-finish-load), mais sera rejettée si la page ne parvient pas à se charger (voir did-fail-load). Un gestionnaire de rejet vide est déjà attaché, ce qui évite les erreurs de rejet non traitées.

Charge l'url dans la fenêtre. Cette url doit contenir le préfixe du protocole, comme par exemple http:// ou file://. Si le chargement doit contourner le cache http, alors utilisez pour cela l'en-tête pragma.

const { webContents } = require('electron')
const options = { extraHeaders: 'pragma: no-cache\n' }
webContents.loadURL('https://github.com', options)

contents.loadFile(filePath[, options])​

  • filePath string
  • options Object (facultatif)
    • query Record<string, string> (facultatif) - Passé à url.format().
    • search string (facultatif) - Passé à url.format().
    • hash string (facultatif) - Passé à url.format().

Retourne Promise<void> - la promesse se résoudra lorsque la page aura terminé le chargement (voir did-finish-load), et rejette si la page ne parvient pas à se charger (voir did-fail-load).

Charge le fichier donné dans la fenêtre, filePath doit être le chemin d'un fichier HTML et relatif par rapport à la racine de votre application. Par exemple une structure d'application comme celle-ci :

| root
| - package.json
| - src
|   - main.js
|   - index.html

Nécessitera du code comme celui ci

win.loadFile('src/index.html')

contents.downloadURL(url)​

  • url string

Lance le téléchargement de la ressource située à l'url sans naviguer. L'événement will-download de session sera déclenché.

contents.getURL()​

Retourne string - l'URL de la page web courante.

const { BrowserWindow } = require('electron')
const win = new BrowserWindow({ width: 800, height: 600 })
win.loadURL('http://github.com').then(() => {
  const currentURL = win.webContents.getURL()
  console.log(currentURL)
})

contents.getTitle()​

Retourne string - le titre de la page web courante.

contents.isDestroyed()​

Retourne boolean - Indique si la page web est détruite.

contents.close([opts])​

  • opts Object (facultatif)
    • waitForBeforeUnload booléen - si true, l'événement beforeunload sera déclenché avant la fermeture de la page. Si la page empêche le déchargement, le WebContents ne sera pas fermé. Dans un tel cas l'événement will-prevent-unload sera déclenché.

Ferme la page, comme si le contenu web avait exécuté window.close().

Si la page est fermée avec succès (c'est à dire que le déchargement n'est pas empêché par la page, que ou waitForBeforeUnload est à false ou non spécifié), lWebContents sera supprimé et plus utilisable. L'événement destroyed sera alors émis.

contents.focus()​

Met au premier plan la page web.

contents.isFocused()​

Retourne boolean - Indique si la page Web a le focus.

contents.isLoading()​

Retourne boolean - Indique si la page Web est encore en train de charger des ressources.

contents.isLoadingMainFrame()​

Retourne boolean - Si la frame principale (et pas seulement un iframe ou frames qu'il contient) sont toujours en chargement.

contents.isWaitingForResponse()​

Retourne boolean -Indique si la page web est en attente d'une première réponse de la principale ressource de la page.

contents.stop()​

Arrête toute navigation en attente.

contents.reload()​

Recharge la page web courante.

contents.reloadIgnoringCache()​

Recharge la page courante et ignore le cache.

contents.canGoBack()​

Retourne boolean - Indique si le navigateur peut revenir à la page Web précédente.

contents.canGoForward()​

Retourne boolean - Indique si le navigateur peut aller à la page Web suivante.

contents.canGoToOffset(offset)​

  • offset Integer

Retourne boolean - Indique si la page web peut aller à offset.

contents.clearHistory()​

Efface l'historique de navigation.

contents.goBack()​

Fait revenir le navigateur en arrière d'une page web.

contents.goForward()​

Fait avancer le navigateur d'une page web.

contents.goToIndex(index)​

  • index Integer

Fait naviguer le navigateur vers l'index de page web absolu spécifié.

contents.goToOffset(offset)​

  • offset Integer

Navigue vers l'offset spécifié à partir de l' "entrée courante".

contents.isCrashed()​

Retourne boolean - Indique si le processus de rendu a planté.

contents.forcefullyCrashRenderer()​

Termine énergiquement le processus de rendu qui héberge actuellement ce webContents. Cela provoquera l'émission de l'événement render-process-gone indiquant la cause avec reason=killed || reason=crashed. Veuillez noter que certains webContents se partagent un même processus de rendu et donc que l'appel de cette méthode par d'autres webContents peut également faire planter le processus hôte. .

L'appeler à reload() immédiatement après avoir appelé cette méthode forcera le rechargement à se produire dans un nouveau processus. Ceci devra être utilisé lorsque le processus est instable ou inutilisable, par exemple pour se rétablir suite à l'événement unresponsive.

contents.on('unresponsive', async () => {
  const { response } = await dialog.showMessageBox({
    message: 'App X has become unresponsive',
    title: 'Do you want to try forcefully reloading the app?',
    buttons: ['OK', 'Cancel'],
    cancelId: 1
  })
  if (response === 0) {
    contents.forcefullyCrashRenderer()
    contents.reload()
  }
})

contents.setUserAgent(userAgent)​

  • userAgent string

Surcharge l'agent utilisateur de cette page web.

contents.getUserAgent()​

Retourne string - l'agent utilisateur de la page web.

contents.insertCSS(css[, options])​

  • css string
  • options Object (facultatif)
    • cssOrigin string (facultatif) - Peut être 'user' ou 'author'. Définit l'origine de la cascade de la feuille de style insérée. La valeur par défaut est 'author'.

Retourne Promise<string> - Une promesse qui se résout avec une clé pour le CSS inséré qui peut être utilisé plus tard pour supprimer le CSS via contents.removeInsertedCSS(key).

Injecte du CSS dans la page Web actuelle et renvoie une clé unique pour la feuille de style insérée .

contents.on('did-finish-load', () => {
  contents.insertCSS('html, body { background-color: #f00; }')
})

contents.removeInsertedCSS(key)​

  • key string

Retourne Promise<void> - se résolvant si la suppression a réussi.

Supprime de la page web actuelle le CSS inséré. La feuille de style est identifiée par sa clé, qui est retournée par contents.insertCSS(css).

contents.on('did-finish-load', async () => {
  const key = await contents.insertCSS('html, body { background-color: #f00; }')
  contents.removeInsertedCSS(key)
})

contents.executeJavaScript(code[, userGesture])​

  • code string
  • userGesture boolean (facultatif) - false par défaut.

Retourne Promise<any> - Une promesse qui se résout avec le résultat du code exécuté ou se rejette si le résultat du code est une promesse rejetée.

Évalue le code dans la page.

Dans la fenêtre du navigateur, certaines APIs HTML comme requestFullScreen peut être invoqué seulement par un geste de l'utilisateur. Définir userGesture à true supprimera cette limitation.

L'exécution du code sera suspendue jusqu'à la fin du chargement de la page web.

contents.executeJavaScript('fetch("https://jsonplaceholder.typicode.com/users/1").then(resp => resp.json())', true)
  .then((result) => {
    console.log(result) // sera l'objet JSON de l'appel à fetch
})

contents.executeJavaScriptInIsolatedWorld(worldId, scripts[, userGesture])​

  • worldId Integer - L'ID du monde dans lequel exécuter le javascript, 0 est le monde par défaut, 999 est le monde utilisé par la fonctionnalité contextIsolation d'Electron. Sinon vous pouvez fournir n'importe quel entier.
  • scripts WebSource[]
  • userGesture boolean (facultatif) - false par défaut.

Retourne Promise<any> - Une promesse qui se résout avec le résultat du code exécuté ou se rejette si le résultat du code est une promesse rejetée.

Fonctionne comme executeJavaScript mais en évaluant le scripts dans un contexte isolé.

contents.setIgnoreMenuShortcuts(ignore)​

  • ignore boolean

Ignorer les raccourcis du menu des applications lorsque ce contenu Web a le focus.

contents.setWindowOpenHandler(handler)​

  • handler Function<{action: 'deny'} | {action: 'allow', outlivesOpener?: boolean, overrideBrowserWindowOptions?: BrowserWindowConstructorOptions}>

    • Objet details
      • url string - La a résolu la version de l'URL passée à window.open(). par exemple, ouvrir une fenêtre avec window.open('foo') donnera quelque chose comme https://the-origin/the/current/path/foo.
      • frameName string - Nom de la fenêtre fourni dans window.open()
      • features string - Liste séparée par des virgules des fonctionnalités de fenêtre fournies à window.open().
      • disposition string - Peut être default, foreground-tab, background-tab, new-window, save-to-disk et other.
      • referrer Referrer - L'origine qui sera passée à la nouvelle fenêtre. Peut selon la politique du référent entraîner ou non l'envoi de l'en-tête du Referer .
      • postBody PostBody (facultatif) - Les données envoyées à la nouvelle fenêtre, ainsi que les en-têtes appropriés qui seront définis. Si aucune donnée ne doit être envoyée, la valeur sera null. Défini uniquement dans le cas où la fenêtre est créée par un formulaire définissant target=_blank.

    Retourne {action: 'deny'} | {action: 'allow', outlivesOpener?: boolean, overrideBrowserWindowOptions?: BrowserWindowConstructorOptions} - deny annule la création de la nouvelle fenêtre. . allow permettra la création de la nouvelle fenêtre. La spécification de overrideBrowserWindowOptions permet de personnaliser la fenêtre créée. Par défaut, les fenêtres enfants sont fermées lorsque l'élément qui les a ouvertes est lui même fermé. Cela peut être modifié en spécifiant outlivesOpener: true, auquel cas la fenêtre enfant demeurera ouverte. Le retour d’une valeur non reconnue telle que null, undefined ou d'un objet dont la propriété ’action' n'est pas reconnue entraînera une erreur dans la console et aura le même effet que le retour de {action: 'deny'}.

Appelé avant la création d'une fenêtre, une nouvelle fenêtre est demandée par le moteur de rendu, p. ex. par window.open(), un lien avec target="_blank", Maj + clic sur un lien, ou soumettant un formulaire avec <form target="_blank">. Voir window.open() pour plus de détails et comment l'utiliser en conjonction avec did-create-window.

contents.setAudioMuted(muted)​

  • muted boolean

Couper le son sur la page web actuelle.

contents.isAudioMuted()​

Renvoie boolean - Si cette page a été rendu muette.

contents.isCurrentlyAudible()​

Retourne boolean - Indique si l'audio est en cours de lecture.

contents.setZoomFactor(factor)​

  • factor Double - Facteur de zoom ; la valeur par défaut est 1.0.

Modifie le facteur de zoom en utilisant le facteur spécifié. Le Zoom factor est égal à la valeur du zoom exprimée en pourcent divisée par 100, donc 300% = 3.0.

Le rapport doit être supérieur à 0.0.

contents.getZoomFactor()​

Retourne number - Le facteur de zoom actuel.

contents.setZoomLevel(level)​

  • level number - Niveau de zoom.

Modifie le niveau de zoom jusqu'au niveau spécifié. La taille originale est de 0 et chaque incrément au-dessus ou en dessous représente un zoom de 20% supérieur ou inférieure jusqu'au limites de 300% et 50% de la taille originale, respectivement. La formule pour cela est 'scale:= 1,2 ^ level.

NOTE: La politique du zoom au niveau de Chromium est same-origin, ce qui signifie que le niveau de zoom pour un domaine spécifique se propage à travers toutes les instances de fenêtres du même domaine. Une différenciation de l'URL des fenêtre assignera un niveau de zoom par fenêtre.

contents.getZoomLevel()​

Retourne number - Le niveau de zoom actuel.

contents.setVisualZoomLevelLimits(minimumLevel, maximumLevel)​

  • minimumLevel number
  • maximumLevel number

Retourne Promise<void>

Définit le niveau maximum et minimum le niveau pinch-to-zoom.

NOTE: Le zoom visuel est désactivé par défaut dans Electron. Pour le réactiver:

contents.setVisualZoomLevelLimits(1, 3)

contents.undo()​

Exécute la commande d'édition undo dans la page web.

contents.redo()​

Exécute la commande d'édition redo dans la page web.

contents.cut()​

Exécute la commande d'édition cut dans la page web.

contents.copy()​

Exécute la commande d'édition copy dans la page web.

contents.copyImageAt(x, y)​

  • x Integer
  • y Integer

Copie de l'image à la position donnée dans le presse-papiers.

contents.paste()​

Exécute la commande d'édition paste dans la page web.

contents.pasteAndMatchStyle()​

Exécute la commande d'édition pasteAndMatchStyle dans la page web.

contents.delete()​

Exécute la commande d'édition delete dans la page web.

contents.selectAll()​

Exécute la commande d'édition selectAll dans la page web.

contents.unselect()​

Exécute la commande d'édition unselect dans la page web.

contents.replace(text)​

  • text string

Exécute la commande d'édition replace dans la page web.

contents.replaceMisspelling(text)​

  • text string

Exécute la commande d'édition replaceMisspelling dans la page web.

contents.insertText(text)​

  • text string

Retourne Promise<void>

Insère le text à l'élément ciblé.

contents.findInPage(text[, options])​

  • text string - Contenu à rechercher, ne doit pas être vide.
  • options Object (facultatif)
    • forward boolean (facultatif) - Rechercher soit en avant soit en arrière, la valeur par défaut est true.
    • findNext boolean (facultatif) - Indique si il faut commencer une nouvelle session de recherche de texte avec cette requête. Doit être true pour les requêtes initiales et false pour les requêtes de suivi. Par défaut, false.
    • matchCase boolean (facultatif) - Indique si la recherche doit être sensible à la casse, par défaut à false.

Retourne Integer - L'identifiant de requête utilisé pour la requête.

Démarre une requête pour trouver toutes les concordances avec le text dans la page web. Le résultat de la requête peut être obtenu en s'abonnant à l'événement found-in-page.

contents.stopFindInPage(action)​

  • action string - Spécifie l'action à effectuer à la fin de la requête [webContents.findInPage].
    • clearSelection - Effacer la sélection.
    • keepSelection - Convertir la sélection en une sélection normale.
    • activateSelection - Donne le focus au node de la sélection et effectue un click.

Arrête toute requête findInPage associée à l' action fournie envers le webContents .

const { webContents } = require('electron')
webContents.on('found-in-page', (event, result) => {
  if (result.finalUpdate) webContents.stopFindInPage('clearSelection')
})

const requestId = webContents.findInPage('api')
console.log(requestId)

contents.capturePage([rect, opts])​

  • rect Rectangle (optionnel) - La zone de la page dont on doit réaliser la capture.
  • opts Object (facultatif)
    • stayHidden boolean (facultatif) - Maintient la page cachée au lieu de visible. Par défaut la valeur est false.
    • stayAwake boolean (facultatif) - Maintient le système hors veille. Par défaut la valeur est false.

Retourne Promise<NativeImage> - résout avec une NativeImage

Capture un instantané de la zone de la page définie par rect. Une capture de la page entière sera réalisée en l'absence de rect. The page is considered visible when its browser window is hidden and the capturer count is non-zero. Si vous souhaitez que la page reste cachée, vous devez vous assurer que stayHidden soit bien défini à true.

contents.isBeingCaptured()​

Renvoie boolean - Indique si cette page est en cours de capture. Il renvoie true lorsque le nombre de captattions est supérieur à 0.

contents.getPrinters() Déprécié​

Récupère la liste des imprimantes système.

Retourne PrinterInfo[]

Déprécié : Vous devez utiliser la nouvelle API contents.getPrintersAsync.

contents.getPrintersAsync()​

Récupère la liste des imprimantes système.

Retourne Promise<PrinterInfo[]> - qui se résout avec un PrinterInfo[]

contents.print([options], [callback])​

  • options Object (facultatif)
    • silent boolean (facultatif) - Ne pas interroger à propos des paramètres d'impression. Par défaut la valeur est false.
    • printBackground boolean (facultatif) - Imprime les couleur et image de fond de la page Web. Par défaut la valeur est false.
    • deviceName string (facultatif) - Définit le nom du périphérique imprimante à utiliser. Doit être le nom défini par le système et non l'appelation, par exemple 'Brother_QL_820NWB' et non 'Brother QL-820NWB'.
    • color booléen (facultatif) - Définit si l'impression de la page se fait en couleur ou en niveaux de gris. La valeur par défaut est true.
    • margins Object (facultatif)
      • marginType string (facultatif) - Peut prendre les valeurs default, none, printableArea, ou custom. Si vous choisissez custom, vous devrez alors également spécifier top, bottom, left et right.
      • top number (facultatif) - Marge supérieure de la page web imprimée, exprimée en pixels .
      • bottom number (facultatif) - Marge inférieure de la page web imprimée, exprimée en pixels .
      • left number (facultatif) - Marge de gauche exprimée en pixels de la page web imprimée.
      • right number (facultatif) -Marge de droite de la page web imprimée, exprimée en pixels .
    • landscape booléen (facultatif) - Indique si la page web doit être imprimée en mode paysage. Par défaut la valeur est false.
    • scaleFactor number (facultatif) - Facteur d'échelle de la page web.
    • pagesPerSheet number (facultatif) - Nombre de pages à imprimer par feuille.
    • collate booléen (facultatif) - Indique si la page web doit être insérée dans un certain ordre.
    • copies number (facultatif) - Nombre de copies à imprimer pour la page Web .
    • pageRanges Object[] (facultatif) - La plage des page à imprimer. Sur macOS, une seule plage est considérée.
      • from number - Index de la première page à imprimer (0-based).
      • to number - Index de la dernière page à imprimer (inclusif) (démarre à 0).
    • duplexMode string (facultatif) - Définit le mode duplex de la page web imprimée. Peut prendre les valeurs simplex, shortEdge, ou longEdge.
    • dpi Record<string, number> (facultatif)
      • horizontal number (facultatif) - Le nombre de dpi en horizontal.
      • vertical number (facultatif) - Le nombre de dpi en vertical.
    • header string (facultatif) - chaîne à imprimer en tant qu'en-tête de page.
    • footer string (facultatif) - chaîne à imprimer en bas de page.
    • pageSize string | Taille (facultatif) - Spécifie la taille du document imprimé. Can be A0, A1, A2, A3, A4, A5, A6, Legal, Letter, Tabloid ou un Object contenant height et width.
  • callback Function (facultatif)
    • success booléen - Indique le succès de l'appel à l'impression.
    • Chaîne failureReason - La description de l'erreur appelée si l'impression échoue.

Lorsqu'un pageSize personnalisée est transmise, Chromium tente de valider par rapport aux valeurs minimales spécifiques à la plate-forme width_microns et height_microns. La largeur et la hauteur doivent être au moins 353 microns mais peuvent être plus élevées sur certains systèmes d'exploitation.

Imprime la page web de la fenêtre. Lorsque silent est défini à true, Electron choisira l'imprimante par défaut du système si deviceName est vide ainsi que les paramètres d'impression par défaut.

Utiliser le style CSS page-break-before: always; pour forcer l'impression vers une nouvelle page.

Exemple d'utilisation :

const options = {
  silent: true,
  deviceName: 'My-Printer',
  pageRanges: [{
    from: 0,
    to: 1
  }]
}
win.webContents.print(options, (success, errorType) => {
  if (!success) console.log(errorType)
})

contents.printToPDF(options)​

  • Objet options
    • landscape booléen (facultatif) - Orientation du papier.true pour le paysage, false pour le portrait. false par défaut.
    • displayHeaderFooter boolean (facultatif) - Indique si on affiche l'en-tête et le pied de page. false par défaut.
    • printBackground boolean (facultatif) - Indique si om imprimer ou non les graphiques en arrière-plan. false par défaut.
    • scale number(facultatif) - Échelle du rendu de la page web. 1 par défaut.
    • pageSize string | Taille (facultatif) - Spécifie la taille de la page du PDF généré. Peut être A0, A1, A2, A3, A4, A5, A6, Legal, Letter, Tabloid, Ledger, ou un objet contenant height et width pouces. Letter par défaut.
    • margins Object (facultatif)
      • top number (facultatif) - Marge supérieure exprimée en pouces. 1cm par défaut (~0.4 pouce).
      • bottom number (facultatif) - Marge inférieure exprimée en pouces. 1cm par défaut (~0.4 pouce).
      • left number (facultatif) - Marge gauche exprimée en pouces. 1cm par défaut (~0.4 pouce).
      • right number (facultatif) - Marge droite exprimée en pouces. 1cm par défaut (~0.4 pouce).
    • pageRanges string (facultatif) - Plage des pages à imprimer, ex: '1-5, 8, 11-13'. Par défaut: une chaîne vide, signifiant d'afficher toutes les pages.
    • headerTemplate string (facultatif) - Modèle du HTML de l'entête d'impression. Doit être un balisage HTML valide avec les classes suivantes utilisées pour y injecter les valeurs d’impression : date (date d’impression formatée), title(titre du document), url(emplacement du document), pageNumber (numéro de page actuel) et totalPages (nombre total de pages dans le document). Par exemple, <span class=title></span> générera un span contenant le titre.
    • footerTemplate string (facultatif) - Modèle du HTML du pied de page d'impression. Doit utiliser le même format que le headerTemplate.
    • preferCSSPageSize boolean (facultatif) - Indique si on optera ou non pour la taille de page définie par le css. Faux par défaut, auquel cas le contenu sera mis à l'échelle pour s'adapter à la taille du papier.

Retourne une Promise<Buffer> -se résolvant avec des données PDF générées.

Imprime en PDF la page web de la fenêtre.

Le landscape sera ignoré si la règle CSS de @page est utilisée dans la page web.

Un exemple de webContents.printToPDF:

const { BrowserWindow } = require('electron')
const fs = require('fs')
const path = require('path')
const os = require('os')

const win = new BrowserWindow()
win.loadURL('http://github.com')

win.webContents.on('did-finish-load', () => {
  // Use default printing options
  const pdfPath = path.join(os.homedir(), 'Desktop', 'temp.pdf')
  win.webContents.printToPDF({}).then(data => {
    fs.writeFile(pdfPath, data, (error) => {
      if (error) throw error
      console.log(`Wrote PDF successfully to ${pdfPath}`)
    })
  }).catch(error => {
    console.log(`Failed to write PDF to ${pdfPath}: `, error)
  })
})

Voir Page.printToPdf pour plus d'informations.

contents.addWorkSpace(path)​

  • path string

Ajoute le chemin spécifié à l'espace de travail des DevTools. Doit être utilisé après la création des DevTools :

const { BrowserWindow } = require('electron')
const win = new BrowserWindow()
win.webContents.on('devtools-opened', () => {
  win.webContents.addWorkSpace(__dirname)
})

contents.removeWorkSpace(path)​

  • path string

Supprime le chemin spécifié de l'espace de travail DevTools.

contents.setDevToolsWebContents(devToolsWebContents)​

  • devToolsWebContents WebContents

Utilise le devToolsWebContents comme la cible WebContents pour afficher les outils de développement.

Le devToolsWebContents ne doit pas avoir fait de navigation, et ne doit pas être utilisé à d'autres fins après l'appel.

Par défaut, Electron gère les devtools en créant un WebContents interne avec une vue native sur laquelle les développeurs ont un contrôle très limité. Avec la méthode setDevToolsWebContents , les développeurs peuvent utiliser n'importe quel WebContents pour afficher les outils de développement dedans, y compris les balises BrowserWindow, BrowserView et <webview> .

Notez que la fermeture des devtools ne détruit pas le devToolsWebContents, il est de la responsabilité de l’appelant de détruire devToolsWebContents.

Exemple d'affichage des devtools dans une balise <webview>:

<html>
<head>
  <style type="text/css">
    * { margin: 0; }
    #browser { height: 70%; }
    #devtools { height: 30%; }
  </style>
</head>
<body>
  <webview id="browser" src="https://github.com"></webview>
  <webview id="devtools" src="about:blank"></webview>
  <script>
    const { ipcRenderer } = require('electron')
    const emittedOnce = (element, eventName) => new Promise(resolve => {
      element.addEventListener(eventName, event => resolve(event), { once: true })
    })
    const browserView = document.getElementById('browser')
    const devtoolsView = document.getElementById('devtools')
    const browserReady = emittedOnce(browserView, 'dom-ready')
    const devtoolsReady = emittedOnce(devtoolsView, 'dom-ready')
    Promise.all([browserReady, devtoolsReady]).then(() => {
      const targetId = browserView.getWebContentsId()
      const devtoolsId = devtoolsView.getWebContentsId()
      ipcRenderer.send('open-devtools', targetId, devtoolsId)
    })
  </script>
</body>
</html>
// Main process
const { ipcMain, webContents } = require('electron')
ipcMain.on('open-devtools', (event, targetContentsId, devtoolsContentsId) => {
  const target = webContents.fromId(targetContentsId)
  const devtools = webContents.fromId(devtoolsContentsId)
  target.setDevToolsWebContents(devtools)
  target.openDevTools()
})

Exemple d'affichage des devtools dans une BrowserWindow:

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

let win = null
let devtools = null

app.whenReady().then(() => {
  win = new BrowserWindow()
  devtools = new BrowserWindow()
  win.loadURL('https://github.com')
  win.webContents.setDevToolsWebContents(devtools.webContents)
  win.webContents.openDevTools({ mode: 'detach' })
})

contents.openDevTools([options])​

  • options Object (facultatif)
    • mode string - Ouvre les devtools avec un positioçnnement spécifié qui peut être left, right, bottom, undocked ou detach. Par défaut, le dernier positionnement utilisé. En mode undocked , il est possible de s’ancrer de nouveau. En mode detach , ce n'est pas le cas.
    • activate booléen (facultatif) - Indiquez s’il faut mettre la fenêtre devtools ouverte au premier plan. Par défaut, true.

Ouvre les devtools.

Quand contents est une balise <webview> , le mode sera detach par défaut, passer explicitement un mode vide peut forcer l'utilisation du dernier état de dock utilisé.

Sous Windows, si la superposition de contrôle Windows est activée, Devtools sera ouvert avec mode: 'detach'.

contents.closeDevTools()​

Ferme les devtools.

contents.isDevToolsOpened()​

Retourne boolean - Si les devtools sont ouvert.

contents.isDevToolsFocused()​

Retourne boolean - Si les devtools ont le focus.

contents.toggleDevTools()​

Active/désactive les outils développeur.

contents.inspectElement(x, y)​

  • x Integer
  • y Integer

Démarre l’inspection de l’élément en position (x, y).

contents.inspectSharedWorker()​

Ouvre les outils de développement pour le contexte de travail partagé.

contents.inspectSharedWorkerById(workerId)​

  • workerId string

Inspecte le processus partagé en fonction de son ID.

contents.getAllSharedWorkers()​

Retourne SharedWorkerInfo[] - Informations sur tous les Workers partagés.

contents.inspectServiceWorker()​

Ouvre les outils de développement pour le contexte deworker partagé.

contents.send(channel, ...args)​

  • channel string
  • ...args any[]

Envoyez un message asynchrone et un certain nombre d'arguments au processus de rendu via channel. . Les arguments seront sérialisés avec le Structured Clone Algorithm, tout comme postMessage, de sorte que les chaînes prototypes ne seront pas incluses. L’envoi de fonctions, de promesses, de symboles, de WeakMaps ou de WeakSets lèvera une exception.

danger

NOTE: L'envoi de types Javascript non standards tels que des objets DOM ou des objets spéciaux Electron est déprécié, et déclenchera une exception.

Pour en savoir plus, reportez-vous au guide IPC d'Electron.

contents.sendToFrame(frameId, channel, ...args)​

  • frameId Integer | [number, number]- l'ID de la frame à envoyer, ou une paire de [processId, frameId] si la frame est dans un processus différent de la principale.
  • channel string
  • ...args any[]

Envoie un message asynchrone au processus principal via channel, ainsi que des arguments. Les arguments seront sérialisés avec le Structured Clone Algorithm, tout comme postMessage, de sorte que les chaînes prototypes ne seront pas incluses. L'envoie de Functions, Promises, Symbols, WeakMaps, ou WeakSets déclenchear une exception.

NOTE: L'envoi de types Javascript non standards tels que des objets DOM ou des objets spéciaux Electron est déprécié, et déclenchera une exception à partir d'Electron 9.

Le processus de rendu peut gérer le message en écoutant sur le channel avec le module ipcRenderer .

Si vous voulez obtenir le frameId d'un contexte de rendu donné, vous devez utiliser la valeur webFrame.routingId. Exemple :

// Dans un processus de rendu
console.log('Mon frameId est:', require('electron').webFrame.routingId)

Vous pouvez également lire frameId de tous les messages IPC entrants dans le processus principal.

// Dans le processus principal
ipcMain.on('ping', (event) => {
  console.info('Le message est venu de frameId:', event.frameId)
})

contents.postMessage(channel, message, [transfer])​

  • channel string
  • message any
  • transfer MessagePortMain[] (facultatif)

Envoie un message au processus de rendu en effectuant éventuellement un transfert de propriété de zéro ou plus objets de type MessagePortMain.

Les objets MessagePortMain transférés seront disponibles dans le processus de rendu en accédant à la propriété ports de l'événement émis. Ils seront des objets DOM MessagePort natifs en arrivant dans le moteur de rendu.

Par exemple :

// Main process
const { port1, port2 } = new MessageChannelMain()
webContents.postMessage('port', { message: 'hello' }, [port1])

// Renderer process
ipcRenderer.on('port', (e, msg) => {
  const [port] = e.ports
  // ...
})

contents.enableDeviceEmulation(parameters)​

  • Objet parameters
    • screenPosition string - Indique le type d'écran à émuler (par défaut: desktop ) :
      • desktop - Desktop screen type.
      • mobile - Mobile screen type.
    • screenSize Size - Défini la taille de l’écran émulé (screenPosition == mobile).
    • viewPosition Point - Positionne la vue sur l'écran (screenPosition == mobile) (par défaut : { x: 0, y: 0 }).
    • deviceScaleFactor Entier - Défini le facteur d’échelle du périphérique (par défaut sur facteur d’échelle du périphérique d’origine si mis à 0) (par défaut : 0).
    • viewSize Size - Défini la taille de l’écran émulé (pas de surcharge si vide)
    • scale Float - Échelle de la vue émulée à l’intérieur de l’espace disponible (non adaptée au mode d’affichage ) (par défaut : 1).

Activer l'émulation de l'appareil avec les paramètres donnés.

contents.disableDeviceEmulation()​

Désactiver l’émulation de périphérique activée par webContents.enableDeviceEmulation.

contents.sendInputEvent(inputEvent)​

Envoie un event d’input à la page. Note: La BrowserWindow incluant le contenu doit avoir le focus pour que sendInputEvent() fonctionne.

contents.beginFrameSubscription([onlyDirty ,]callback)​

  • onlyDirty boolean (optionnel) - false par défaut.
  • callback Function

Commencez à vous abonner aux événements de présentation et aux images capturées, le callback sera appelé avec callback(image, dirtyRect) lorsqu'il y aura un événement de présentation .

L' image est une instance de NativeImage qui stocke la frame capturée.

Le dirtyRect est un objet avec les propriétés x, y, width, height décrivant la partie de la page ayant été repeinte. Si onlyDirty est défini à true, image ne contiendra que la zone repeinte. onlyDirty est par défaut à false.

contents.endFrameSubscription()​

Terminer l'abonnement pour les événements de présentation des frames.

contents.startDrag(item)​

  • item Object
    • file string - Chemin du fichier en cours de déplacement.
    • files string[] (facultatif) - Chemins d’accès aux fichiers à déplacer. (files surchargera le champ file)
    • icon NativeImage string | string - L’image ne doit pas être vide sous macOS.

Définit item comme élément en cours de glissement pour l'opération de glisser-déposer en cours , file est le chemin absolu du fichier à déplacer, et icon est l'image s'affichant sous le curseur lors du glissement.

contents.savePage(fullPath, saveType)​

  • fullPath string - Le chemin absolu du fichier.
  • saveType string - Type d’enregistrement.
    • HTMLOnly - Sauvegarde uniquement du HTML de la page.
    • HTMLComplete - Sauvegarde HTML complete de la page.
    • MHTML - Sauvegarde complete de la page en MHTML.

Retourne une Promise<void> -se résolvantsi la page est enregistrée.

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

win.loadURL('https://github.com')

win.webContents.on('did-finish-load', async () => {
  win.webContents.savePage('/tmp/test.html', 'HTMLComplete').then(() => {
    console.log('Page was saved successfully.')
  }).catch(err => {
    console.log(err)
  })
})

contents.showDefinitionForSelection() macOS​

Affiche un dictionnaire contextuel qui recherche le mot sélectionné sur la page.

contents.isOffscreen()​

Retourne boolean - Indique si l'affichage hors écran est activé.

contents.startPainting()​

Si offscreen rendering est activé et pas en train de repeindre, commencez à peindre.

contents.stopPainting()​

Si offscreen rendering est activé et en train de repeindre, arrêter de repeindre.

contents.isPainting()​

Renvoie boolean - Si offscreen rendering est activé, indique s’il est en cours de peinture.

contents.setFrameRate(fps)​

  • fps Integer

Si offscreen rendering est activé définit la fréquence d’images avec le nombre spécifié. Seules les valeurs comprises entre 1 et 240 sont acceptées.

contents.getFrameRate()​

Renvoie Integer : si offscreen rendering est activé renvoie la fréquence d’images actuelle.

contents.invalidate()​

Planifie une repeinture complète de la fenêtre dans laquelle se trouve ce contenu Web.

Invalide l’image et en génère une nouvelle via l’événement 'paint' si offscreen rendering est activé .

contents.getWebRTCIPHandlingPolicy()​

Renvoie string - Renvoie la stratégie de gestion IP WebRTC.

contents.setWebRTCIPHandlingPolicy(policy)​

  • policy string - Spécifie la stratégie de gestion IP WebRTC.
    • default - Expose les adresses IP publiques et locales de l’utilisateur. C’est le comportement par défaut. Lorsque cette politique est utilisée, WebRTC a le droit d'énumérer toutes les interfaces et de les lier à la découverte d'interfaces publiques.
    • default_public_interface_only - Expose l'adresse IP publique de l'utilisateur, mais n'expose pas l'IP locale de l'utilisateur. Lorsque cette politique est utilisée, WebRTC ne doit utiliser que la route par défaut qui est utilisée par http. Cela n’expose aucune adresse locale.
    • default_public_and_private_interfaces - Expose les adresses IP publiques et locales de l'utilisateur. Lorsque cette politique est utilisée, WebRTC ne doit utiliser que la route par défaut qui est utilisée par http. Cela expose également l'adresse privée associée par défaut . L’itinéraire par défaut est l’itinéraire choisi par le système d’exploitation sur un point de terminaison multi-hébergé.
    • disable_non_proxied_udp - N’expose pas les adresses IP publiques ou locales. Lorsque cette politique est utilisée, WebRTC ne doit utiliser que TCP pour contacter les pairs ou les serveurs, sauf si le serveur proxy prend en charge UDP.

La définition de la stratégie de gestion des adresses IP par WebRTC vous permet de contrôler les adresses IP exposées via WebRTC. Voir BrowserLeaks pour plus de détails.

contents.getMediaSourceId(requestWebContents)​

  • requestWebContents WebContents - contenu Web auquel l’Id sera attribué.

Retourne string - Identifiant d'un flux WebContents. Cet identifiant peut être utilisé avec navigator.mediaDevices.getUserMedia en utilisant un chromeMediaSource de tab. L’identifiant est limité au contenu Web auquel il est attribué et n’est valide que pendant 10 secondes.

contents.getOSProcessId()​

Retourne Integer - Le piddu système d'exploitatiçon correspondant au processus de rendu associé .

contents.getProcessId()​

Retourne Integer - Le pidinterne à Chromium correspondant au processus de rendu associé. Peut- être comparé aux frameProcessId transmis par des événements de navigation spécifiques à une image (par exemple, did-frame-navigate)

contents.takeHeapSnapshot(filePath)​

  • filePath string - Chemin vers le fichier de sortie.

Retourne Promise<void> - Indique si l'instantané a été créé avec succès.

Prend un instantané de tas V8 et l'enregistre dans filePath.

contents.getBackgroundThrottling()​

Retourne boolean - si ou non ce WebContents limitera les animations et les timers lorsque la page est en arrière-plan. Cela affecte également l'API de Visibilité de page.

contents.setBackgroundThrottling(allowed)​

  • allowed boolean

Contrôle si ce contenu Web limitera ou non les animations et les minuteries lorsque la page passe en arrière-plan. Cela affecte également l'API de Visibilité de page.

contents.getType()​

Retourne string - type du contenu web. Peut prendre les valeurs backgroundPage, window, browserView, remote, webview ou offscreen.

contents.setImageAnimationPolicy(policy)​

  • policy string - Peut prendre une des valeurs animate, animateOnce ou noAnimation.

Définit la stratégie d’animation d’image pour ce contenu Web. La stratégie n’affecte que nouvelles images , les images existantes en cours d’animation ne sont pas affectées. Il s’agit d’une limitation connue dans Chromium, vous pouvez forcer l’animation d’image à être recalculée avec img.src = img.src ce qui n’entraînera aucun trafic réseau mais mettra à jour la stratégie d’animation.

Cela correspond à la fonctionnalité d’accessibilité animationPolicy de Chromium.

Propriétés d'instance​

contents.ipc Lecture seule​

Un IpcMain limité aux messages IPC envoyés à partir de ce WebContents.

Les messages IPC envoyés en invoquant ipcRenderer.send, ipcRenderer.sendSync ou ipcRenderer.postMessage seront envoyés dans l'ordres suivant :

  1. contents.on('ipc-message')
  2. contents.mainFrame.on(channel)
  3. contents.ipc.on(channel)
  4. ipcMain.on(channel)

Les gestionnaires enregistrés pour invoke seront vérifiés dans la commande suivante. Le premier défini sera appelé, le reste sera ignoré.

  1. contents.mainFrame.handle(channel)
  2. contents.handle(channel)
  3. ipcMain.handle(channel)

Un gestionnaire ou un event listener enregistré sur le WebContents recevra les messages IPC envoyés depuis n'importe quelle frame, y compris les frames enfants. Dans la plupart des cas, seule la frame principale peut envoyer des messages IPC. Cependant, si l'option nodeIntegrationInSubFrames est activée, il est possible pour les frames enfants d'envoyer des messages IPC. Dans ce cas, les gestionnaires devront vérifier la propriété senderFrame de l'événement IPC pour s'assurer que le message provient bien de la framee attendue. Sinon il est également possible d'enregistrer directement les gestionnaires sur la frame appropriée en utilisant l'interface WebFrameMain.ipc.

contents.audioMuted​

Propriété boolean qui détermine si cette page est mise en sourdine.

contents.userAgent​

Propriété string qui détermine l'agent utilisateur pour cette page web.

contents.zoomLevel​

Propriété number qui détermine le niveau de zoom de ce contenu Web.

La taille d’origine est 0 et chaque incrément au dessus ou en dessous représente un zoom de 20 % plus grand ou plus petit jusqu’aux limites par défaut de 300 % et 50 % de la taille d’origine, respectivement. La formule utilisée pour cela est scale := 1.2 ^ level.

contents.zoomFactor​

Propriété number qui détermine le facteur de zoom pour ce contenu Web.

Le facteur de zoom est le pourcentage de zoom divisé par 100, donc 300% = 3.0.

contents.frameRate​

Propriété Integer qui définit la fréquence d’images du contenu Web avec le nombre spécifié. Seules les valeurs comprises entre 1 et 240 sont acceptées.

Ne s'applique que si offscreen rendering est activé.

contents.id Lecture seule​

Un Integer représentant l'ID unique de ce contenu Web. Chaque ID est unique parmi ceux des instances de WebContents de l'application Electron.

contents.session Lecture seule​

Session utilisée par ce webContents.

contents.hostWebContents Lecture seule​

Une instance de WebContents pouvant posséder ce WebContents.

contents.devToolsWebContents Lecture seule​

Propriété WebContents | null qui représente le WebContents DevTools associé à un WebContentsdonné.

Note: les utilisateurs ne doivent jamais mémoriser cet objet, car il peut devenir null lorsque les DevTools sont fermés.

contents.debugger Lecture seule​

Une instance de Debugger pour ce contenu web.

contents.backgroundThrottling​

Propriété boolean qui détermine si ce Contenu Web limitera ou non les animations et les timers lorsque la page passe en arrière-plan. Cela affecte également l'API de Visibilité de page.

contents.mainFrame Lecture seule​

Propriété WebFrameMain qui représente la frame au plus haut niveau dans la hiérarchie de frames de la page.

contents.opener Lecture seule​

Propriété de type WebFrameMain représentant la frame ayant ouvert ce WebContents, soit avec open(), soit en naviguant à partir d'un lien avec un attribut target.