webContents
Gestion des pages web et de 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)
Événements de navigation
Plusieurs événements peuvent être utilisés pour surveiller les navigations qui se produisent dans un webContents
.
Navigations de documents
Lorsqu'un webContents
navigue vers une autre page (par opposition à une navigation sur la page), les événements suivants seront déclenchés.
did-start-navigation
will-frame-navigate
will-navigate
(déclenché uniquement lorsque la frame principale navigue)will-redirect
(déclenché uniquement quand une redirection se produit pendant la navigation)did-redirect-navigation
(déclenché uniquement quand une redirection se produit pendant la navigation)did-frame-navigate
did-navigate
(déclenché uniquement lorsque la frame principale navigue)
Les événements ultérieus ne se déclencheront pas si event.preventDefault()
est appelé sur l'un des événements annulables.
Navigation dans la page
Les navigations dans les pages ne provoquent pas le rechargement de la page, mais plutôt la navigation vers un emplacement dans la page courante. Ces événements ne sont pas annulables. Pour une navigation dans la page, les événements suivants vont se déclencher dans cet ordre:
Navigation dans la fenêtre
Les événements will-navigate
et did-navigate
ne se déclenchent que lorsque le mainFrame navigue. If you want to also observe navigations in <iframe>
s, use will-frame-navigate
and did-frame-navigate
events.
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
- Une instance de WebContents dont l'ID est donné, ou undefined
si aucun contenu Web n’est associé à l'ID donné.
webContents.fromFrame(frame)
frame
WebFrameMain
Retourne WebContents | undefined
- Une instance de WebContents dont la WebFrameMain est donné, ou undefined
si aucun contenu Web n’est associé à la WebFrameMain.
webContents.fromDevToolsTargetId(targetId)
targetId
string - Le protocole Chrome DevTools TargetID associé à l'instance WebContents.
Retourne WebContents | undefined
- Une instance de WebContents dont le TargetID est donné, ou undefined
si aucun contenu Web n’est associé au TargetID.
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 wc.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
EventerrorCode
IntegererrorDescription
stringvalidatedURL
stringisMainFrame
booleanframeProcessId
IntegerframeRoutingId
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
EventerrorCode
IntegererrorDescription
stringvalidatedURL
stringisMainFrame
booleanframeProcessId
IntegerframeRoutingId
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
EventisMainFrame
booleanframeProcessId
IntegerframeRoutingId
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
Eventtitle
stringexplicitSet
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
Eventfavicons
string[] - Tableau d'URLs.
Émis lorsque la page reçoit l’url du favicon.
Événement : 'content-bounds-updated'
Retourne :
event
Eventbounds
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()
.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êteReferer
.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 seranull
. Est uniquement défini lorsque la fenêtre est créée par un formulaire définissanttarget=_blank
.disposition
string - La valeur peut êtredefault
,foreground-tab
,background-tab
,new-window
ouother
.
É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 :
details
Event<>url
string - L'URL vers laquelle la frame est en train de naviguer.isSameDocument
boolean - This event does not fire for same document navigations using window.history api and reference fragment navigations. Cette propriété est toujours définie àfalse
pour cet événement.isMainFrame
booléen - Vrai si la navigation se déroule dans une frame principale.frame
WebFrameMain - The frame to be navigated.initiator
WebFrameMain (optional) - The frame which initiated the navigation, which can be a parent frame (e.g. viawindow.open
with a frame's name), or null if the navigation was not initiated by a frame. This can also be null if the initiating frame was deleted before the event was emitted.
url
chaîne __ DépréciéisInPlace
boolean__ DépréciéisMainFrame
boolean__ DépréciéframeProcessId
Integer__ DépréciéframeRoutingId
Integer __ Déprécié
Émis lorsqu'un utilisateur ou la page veut démarrer la navigation dans la frame principale. 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 grâce aux APIs comme webContents.loadURL
et 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
. Vous devez utiliser pour cela l'événement did-navigate-in-page
.
Appeler event.preventDefault()
permet d'éviter la navigation.
Événement : 'will-frame-navigate'
Retourne :
details
Event<>url
string - L'URL vers laquelle la frame est en train de naviguer.isSameDocument
boolean - This event does not fire for same document navigations using window.history api and reference fragment navigations. Cette propriété est toujours définie àfalse
pour cet événement.isMainFrame
booléen - Vrai si la navigation se déroule dans une frame principale.frame
WebFrameMain - The frame to be navigated.initiator
WebFrameMain (optional) - The frame which initiated the navigation, which can be a parent frame (e.g. viawindow.open
with a frame's name), or null if the navigation was not initiated by a frame. This can also be null if the initiating frame was deleted before the event was emitted.
Émis lorsqu'un utilisateur ou la page veut démarrer la navigation dans n'importe quelle frame. Cela peut se produire lorsque l’objet window.location
est modifié ou qu’un utilisateur clique sur un lien dans la page.
Contrairement à will-navigate
, will-frame-navigate
est déclenché lorsque la frame principale ou l'une de ses sous-frame tente de naviguer. Lorsque l'événement de navigation vient de la frame principale, isMainFrame
sera à true
.
Cet événement ne sera pas émis lorsque la navigation démarre par programmation grâce aux APIs comme webContents.loadURL
et 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
. Vous devez utiliser pour cela l'événement did-navigate-in-page
.
Appeler event.preventDefault()
permet d'éviter la navigation.
Événement : 'did-start-navigation'
Retourne :
details
Event<>url
string - L'URL vers laquelle la frame est en train de naviguer.isSameDocument
boolean - Indique si la navigation s'est produite sans modifier le document . Examples of same document navigations are reference fragment navigations, pushState/replaceState, and same page history navigation.isMainFrame
booléen - Vrai si la navigation se déroule dans une frame principale.frame
WebFrameMain - The frame to be navigated.initiator
WebFrameMain (optional) - The frame which initiated the navigation, which can be a parent frame (e.g. viawindow.open
with a frame's name), or null if the navigation was not initiated by a frame. This can also be null if the initiating frame was deleted before the event was emitted.
url
chaîne __ DépréciéisInPlace
boolean__ DépréciéisMainFrame
boolean__ DépréciéframeProcessId
Integer__ DépréciéframeRoutingId
Integer __ Déprécié
Émis lorsqu’une frame (y compris principale) commence à naviguer.
Événement : 'will-redirect'
Retourne :
details
Event<>url
string - L'URL vers laquelle la frame est en train de naviguer.isSameDocument
boolean - Indique si la navigation s'est produite sans modifier le document . Examples of same document navigations are reference fragment navigations, pushState/replaceState, and same page history navigation.isMainFrame
booléen - Vrai si la navigation se déroule dans une frame principale.frame
WebFrameMain - The frame to be navigated.initiator
WebFrameMain (optional) - The frame which initiated the navigation, which can be a parent frame (e.g. viawindow.open
with a frame's name), or null if the navigation was not initiated by a frame. This can also be null if the initiating frame was deleted before the event was emitted.
url
chaîne __ DépréciéisInPlace
boolean__ DépréciéisMainFrame
boolean__ DépréciéframeProcessId
Integer__ DépréciéframeRoutingId
Integer __ Déprécié
É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 :
details
Event<>url
string - L'URL vers laquelle la frame est en train de naviguer.isSameDocument
boolean - Indique si la navigation s'est produite sans modifier le document . Examples of same document navigations are reference fragment navigations, pushState/replaceState, and same page history navigation.isMainFrame
booléen - Vrai si la navigation se déroule dans une frame principale.frame
WebFrameMain - The frame to be navigated.initiator
WebFrameMain (optional) - The frame which initiated the navigation, which can be a parent frame (e.g. viawindow.open
with a frame's name), or null if the navigation was not initiated by a frame. This can also be null if the initiating frame was deleted before the event was emitted.
url
chaîne __ DépréciéisInPlace
boolean__ DépréciéisMainFrame
boolean__ DépréciéframeProcessId
Integer__ DépréciéframeRoutingId
Integer __ Déprécié
É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
Eventurl
stringhttpResponseCode
Integer - -1 fpour les navigations non HTTPhttpStatusText
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
. Vous devez utiliser pour cela l'événement did-navigate-in-page
.
Événement : 'did-navigate'
Retourne :
event
Eventurl
stringhttpResponseCode
Integer - -1 fpour les navigations non HTTPhttpStatusText
string - vide pour les navigations non HTTP,isMainFrame
booleanframeProcessId
IntegerframeRoutingId
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
. Vous devez utiliser pour cela l'événement did-navigate-in-page
.
Événement : 'did-navigate-in-page'
Retourne :
event
Eventurl
stringisMainFrame
booleanframeProcessId
IntegerframeRoutingId
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
Eventkilled
boolean
Émis lorsque le processus renderer crash ou est interrompu.
Déprécié: Cet événement est remplacé par l'événement render-process-gone
qui contient plus d'informations à propos de la cause du plantage 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
Eventdetails
RenderProcessGoneDetails
É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
Eventname
stringversion
string
Émis lorsqu’un processus de plugin crash.
Événement : 'destroyed'
Émis lorsqu'un webContents
est détruit.
Événement : 'before-input-event'
Retourne :
event
EventinputEvent
InputEvent
É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 :
event
Eventinput
Object - Propriétés d’input.type
string - Les valeurs possibles sontkeyUp
etkeyDown
.key
string - Équivalent à KeyboardEvent.key.code
string - Équivalent à KeyboardEvent.code.isAutoRepeat
boolean - Équivalent à KeyboardEvent.repeat.isComposing
booléen - Équivalent à KeyboardEvent.isComposing.shift
boolean - Équivalent à KeyboardEvent.shiftKey.control
boolean - Équivalent à KeyboardEvent.controlKey.alt
boolean - Équivalent à KeyboardEvent.altKey.meta
boolean - Équivalent à KeyboardEvent.metakey.location
number - 'Equivalent à KeyboardEvent.location.modifiers
string[] - Voir InputEvent.modifiers.
É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
EventzoomDirection
string - Les valeurs possibles sontin
etout
.
É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'
Retourne :
event
Eventurl
string - URL du lien qui a été cliqué ou sélectionné.
Émis lorsqu'un lien est cliqué dans DevTools ou qu'"Ouvrir dans un nouvel onglet" est sélectionné pour un lien dans son menu contextuel.
É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
Eventurl
stringerror
string - Le code d'erreur.certificate
Certificatecallback
FunctionisTrusted
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 identique à l'événement certificate-error
de app
.
Événement : 'select-client-certificate'
Retourne :
event
Eventurl
URLcertificateList
Certificate[]callback
Functioncertificate
Certificate - Doit être un des certificats de la liste donnée.
Émis lorsqu'un certificat client est demandé.
L'utilisation est identique à l'événement select-client-certificate
de app
.
Événement : 'login'
Retourne :
event
Event- Objet
authenticationResponseDetails
url
URL
- Objet
authInfo
isProxy
booleanscheme
stringhost
stringport
Integerrealm
string
callback
Functionusername
string (facultatif)password
string (facultatif)
Émis lorsque webContents
veut faire une authentification normale.
L'utilisation est identique à l'événement login
de app
.
Événement : 'found-in-page'
Retourne :
event
Eventresult
ObjectrequestId
IntegeractiveMatchOrdinal
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 suite à une 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 : 'audio-state-changed'
Retourne :
event
Event<>audible
booléen - Vrai si une ou plusieurs frames ouwebContents
enfants émettent de l'audio.
Émis lorsque les médias deviennent audibles ou inaudibles.
Événement : 'did-change-theme-color'
Retourne :
event
Eventcolor
(string | null) - La couleur du thème est au format '#rrggbb'. Il estnull
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
Eventurl
string
Émis lorsque la souris passe sur un lien ou le clavier déplace le focus vers un lien.
Événement : 'cursor-changed'
Retourne :
event
Eventtype
stringimage
NativeImage (facultatif)scale
Float (facultatif) - Facteur de mise à l'échelle pour le curseur personnalisé.size
Size (facultatif) - Taille d'image
.hotspot
Point (facultatif) - Coordonnées du point actif du curseur personnalisé.
Émis lorsque le type du curseur change. Le paramètre type
peut prenrde une des valeurs suivantes: pointer
, crosshair
, hand
, 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
, m-panning-vertical
, m-panning-horizontal
, 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
, custom
, null
, drag-drop-none
, drag-drop-move
, drag-drop-copy
, drag-drop-link
, ns-no-resize
, ew-no-resize
, nesw-no-resize
, nwse-no-resize
, ou default
.
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
Eventparams
Objectx
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 node 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 de plus haut niveau d'où le menu contextuel a été appelé.frameURL
string - L'URL de la subframe d'où le menu contextuel a été appelé.- 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 de node par lequel le menu contextuel a été appelé. Peut êtrenone
,image
,audio
,vidéo
,toile
,fichier
ouplugin
.hasImageContents
boolean - Indique si le menu contextuel a été appelé à partir d'une image au contenu non-vide.isEditable
boolean - Indique si le contexte est modifiable ou pas.selectionText
string - Texte de la sélection à partir de laquelle le menu contextuel a été appelé.titleText
string : Texte dutitle
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 - The misspelled word under the cursor, if any.dictionarySuggestions
string[] - An array of suggested words to show the user to replace themisspelledWord
. Uniquement disponible si un mot est mal orthographié et que le correcteur orthographique est activé.frameCharset
string - The character encoding of the frame on which the menu was invoked.inputFieldType
string - If the context menu was invoked on an input field, the type of that field. Les valeurs possibles incluentnone
,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 valeursnone
,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 s'est planté.isPaused
boolean - Indique si l'élément multimédia est en pause.isMuted
boolean - Indique si le son de l'élément multimédia est coupé.hasAudio
boolean - Si l'élément multimédia possède une piste audio.isLooping
boolean - Indique si l'élément multimédia est en boucle.isControlsVisible
boolean - Indique si les contrôles de l'élément multimédia sont visibles.canToggleControls
boolean - Si les contrôles de l'élément multimédia peuvent être acivés ou désactivés.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 - Indique si on peut faire pivoter l'élément multimédia.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 - Indique si le moteur de rendu estime pouvoir aller en arrière.canRedo
boolean - Indique si le moteur de rendu estimepouvoir aller en avant.canCut
boolean - Indique si le moteur de rendu estime pouvoir couper.canCopy
boolean - Indique si le moteur de rendu estime pouvoir copier.canPaste
boolean - Indiqe si le moteur de rendu estime pouvoir coller.canDelete
boolean - Indique si le moteur de rendu estime pouvoir supprimer.canSelectAll
boolean - Indiqe si le moteur de rendu estime 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 a besoin d'être pris en charge.
Événement : 'select-bluetooth-device'
Retourne :
event
Eventdevices
BluetoothDevice[]callback
FunctiondeviceId
string
É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.
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 :
event
EventdirtyRect
Rectangleimage
NativeImage - Les données de l'image de la frame entière.
É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
EventwebPreferences
WebPreferences - Les préférences web qui seront utilisées par la page hôte. 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'URLsrc
. 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
EventwebContents
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
Eventlevel
Integer - Le niveau de logging, de 0 à 3. Correspondant dans l'ordre croissant àverbose
,info
,warning
eterror
.message
string - Message actuel de la consoleline
Integer - Numéro de la ligne du source qui a déclenché le message affiché dans la consolesourceId
string
Émis lorsque la fenêtre associée affiche un message de log dans la console.
Événement : 'preload-error'
Retourne :
event
EventpreloadPath
stringerror
Error
Émis lorsque le script de préchargement preloadPath
lance une exception non gérée error
.
Événement : 'ipc-message'
Retourne :
event
IpcMainEventchannel
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
IpcMainEventchannel
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
EventpreferredSize
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
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 win = new BrowserWindow()
const options = { extraHeaders: 'pragma: no-cache\n' }
win.webContents.loadURL('https://github.com', options)
contents.loadFile(filePath[, options])
filePath
string
Retourne une Promise<void>
- la promesse se résoudra lorsque la page aura terminé le chargement (voir did-finish-load
), et rejettée 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
const win = new BrowserWindow()
win.loadFile('src/index.html')
contents.downloadURL(url[, options])
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énementbeforeunload
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énementwill-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
.
const win = new BrowserWindow()
win.webContents.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) {
win.webContents.forcefullyCrashRenderer()
win.webContents.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
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 .
const win = new BrowserWindow()
win.webContents.on('did-finish-load', () => {
win.webContents.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)
.
const win = new BrowserWindow()
win.webContents.on('did-finish-load', async () => {
const key = await win.webContents.insertCSS('html, body { background-color: #f00; }')
win.webContents.removeInsertedCSS(key)
})
contents.executeJavaScript(code[, userGesture])
code
stringuserGesture
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.
const win = new BrowserWindow()
win.webContents.executeJavaScript('fetch("https://jsonplaceholder.typicode.com/users/1").then(resp => resp.json())', true)
.then((result) => {
console.log(result) // Sera l'objet JSON provenant 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 avecwindow.open('foo')
donnera quelque chose commehttps://the-origin/the/current/path/foo
.frameName
string - Nom de la fenêtre fourni danswindow.open()
features
string - Liste séparée par des virgules des fonctionnalités de fenêtre fournies àwindow.open()
.disposition
string - La valeur peut êtredefault
,foreground-tab
,background-tab
,new-window
ouother
.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 duReferer
.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 seranull
. Défini uniquement dans le cas où la fenêtre est créée par un formulaire définissanttarget=_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 deoverrideBrowserWindowOptions
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écifiantoutlivesOpener: 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'}
.- Objet
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
numbermaximumLevel
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:
const win = new BrowserWindow()
win.webContents.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.centerSelection()
Centre la sélection de texte en cours dans la page Web.
contents.copyImageAt(x, y)
x
Integery
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.scrollToTop()
Défile vers le haut de la webContents
actuelle.
contents.scrollToBottom()
Défile vers le bas de la webContents
actuelle.
contents.adjustSelection(options)
- Objet
options
start
Number (facultatif) - Valeur du déplacement de l'index de début de la sélection actuelle.end
Number (facultatif) - Valeur du déplacement de l'index de fin de la sélection actuelle.
Ajuste les points de début et de fin de la sélection de texte en cours dans la frame ayant le focus sur les valeurs indiquées. Une valeur négative déplacera la sélection vers le début du document et une positive vers la fin du document.
Exemple :
const win = new BrowserWindow()
// Ajuste le début de la sélection d'une lettre vers l'avant,
// et la fin de la sélection de 5 lettres vers l'avant.
win.webContents.adjustSelection({ start: 1, end: 5 })
// Ajuste le début de la sélection de deux lettres vers l'avant,
// et la fin de la sélection de 3 lettres vers l'arrière.
win.webContents.adjustSelection({ start: 2, end: -3 })
Pour un appel à win.webContents.adjustSelection({ start: 1, end: 5 })
Avant:

Après:

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.
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êtewebContents.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 win = new BrowserWindow()
win.webContents.on('found-in-page', (event, result) => {
if (result.finalUpdate) win.webContents.stopFindInPage('clearSelection')
})
const requestId = win.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 estfalse
.stayAwake
boolean (facultatif) - Maintient le système hors veille. Par défaut la valeur estfalse
.
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
. La page est considérée visible lorsque sa BrowserWindow est cachée et que le nombre de captations n'est pas nul. 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])
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 win = new BrowserWindow()
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 êtreA0
,A1
,A2
,A3
,A4
,A5
,A6
,Legal
,Letter
,Tabloid
,Ledger
, ou un objet contenantheight
etwidth
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) ettotalPages
(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 leheaderTemplate
.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('node:fs')
const path = require('node:path')
const os = require('node: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
:
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])
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
Integery
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.
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 de destination, ou une paire de[processId, frameId]
si la frame est dans un processus différent de la frame 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
stringmessage
anytransfer
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 :
// Processus principal
const win = new BrowserWindow()
const { port1, port2 } = new MessageChannelMain()
win.webContents.postMessage('port', { message: 'hello' }, [port1])
// Processus s de rendu
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)
inputEvent
MouseInputEvent | MouseWheelInputEvent | KeyboardInputEvent
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
Functionimage
NativeImagedirtyRect
Rectangle
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
Objectfile
string - Chemin du fichier en cours de déplacement.files
string[] (facultatif) - Chemins d’accès aux fichiers à déplacer. (files
surchargera le champfile
)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 pid
du système d'exploitatiçon correspondant au processus de rendu associé .
contents.getProcessId()
Retourne Integer
- Le pid
interne à 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 valeursanimate
,animateOnce
ounoAnimation
.
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 :
contents.on('ipc-message')
contents.mainFrame.on(channel)
contents.ipc.on(channel)
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é.
contents.mainFrame.handle(channel)
contents.handle(channel)
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 WebContents
donné.
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.