dialog

Affiche des boites de dialogue systeme natives pour l’ouverture et l’enregistrement de fichiers, les alertes, etc.

Processus : Main

Par exemple: affichage d'une boite de dialogue pour selectionner plusieurs fichiers :

const
 {
 dialog 
}
 =
 require
(
'electron'
)

console
.
log
(
dialog
.
showOpenDialog
(
{
 properties
:
 [
'openFile'
,
 'multiSelections'
]
 }
)
)

Methodes ?

Le module dialog dispose des methodes suivantes :

dialog.showOpenDialogSync([browserWindow, ]options) ?

• browserWindow BrowserWindow (facultatif)
• Objet options
  • title string (facultatif)
  • defaultPath string (facultatif)
  • buttonLabel string (facultatif) - Label personnalise pour le bouton de confirmation. Si il est laisse vide, le label par defaut sera utilise.
  • filters FileFilter[] (facultatif)
  • properties string[] (facultatif) - Contient les fonctionnalites que la boite de dialogue doit utiliser. Les valeurs suivantes sont prises en charge :
    • openFile - Permet la selection de fichiers.
    • openDirectory - Permet la selection de dossiers.
    • multiSelections - Permet la selection de multiples chemins.
    • showHiddenFiles - Affiche les fichiers caches dans la boite de dialogue.
    • createDirectory macOS - Permet la creation de nouveaux dossiers depuis la boite de dialogue.
    • promptToCreate Windows - Demande la creation du dossier si le chemin d'acces du fichier entre dans la boite de dialogue n'existe pas. Cela ne creer par reellement le fichier dans le chemin d'acces mais permet de donner des chemins d'acces inexistant qui devraient etre crees par l'application.
    • noResolveAliases macOS - Desactive la resolution de l'alias automatique (lien symbolique) . Les alias selectionnes retourneront alors le chemin de l'alias au lieu de celui de leur cible.
    • treatPackageAsDirectory macOS - Considerer les paquets, tels que les dossiers .app , comme des dossiers plutot que des fichiers.
    • dontAddToRecent Windows - Ne pas ajouter l'element en cours d'ouverture a la liste des documents recents.
  • message string (facultatif) macOS - Message a afficher au-dessus des zones de saisie.
  • securityScopedBookmarks boolean (facultatif) macOS MAS - Permet la creation de securityScopedBookmarks lorsqu'ils sont empaquetes pour le Mac App Store.

Retourne string[] | undefined - le chemin du fichier choisi par l'utilisateur ; si la boite de dialogue est annulee retourne undefined .

L'argument browserWindow permet a la boite de dialogue de s'attacher elle-meme a la fenetre parent, la rendant modale.

filters specifie un tableau de types de fichiers qui peuvent etre affiches ou selectionnes lorsque vous voulez limiter l'utilisateur a un type specifique. Par exemple :

{

  filtres
:
 [

    {
 name
 :
 'Images'
,
 extensions
:
 [
'jpg'
,
 'png'
,
 'gif'
]
 }
,

    {
 name
:
 'Films'
,
 extensions
:
 [
'mkv'
,
 'avi'
,
 'mp4'
]
 }
,

    {
 name
:
 'Type de fichier personnalise'
,
 extensions
:
 [
'as'
]
 }
,

    {
 name
:
 'Tous les fichiers'
,
 extensions
:
 [
'*'
]
 }

  ]

}

Le tableau d' extensions doit contenir des extensions sans caracteres generiques ou de point (par exemple 'png' est correct, mais '.png' et '*.png' ne l'est pas). Pour afficher tous les fichiers, utilisez le caractere generique '*' (aucun autre caractere generique n'est pris en charge).

Remarque : Sur Windows et Linux, une boite de dialogue ne peux pas etre a la fois une selection de fichier et une selection de dossier, donc si vous definissez sur ces plateformes properties a ['openFile', 'openDirectory'] , c'est la selection de dossier qui s'affichera.

dialog
.
showOpenDialogSync
(
mainWindow
,
 {

  proprietes
:
 [
'openFile'
,
 'openDirectory'
]

}
)

dialog.showOpenDialog([browserWindow, ]options) ?

• browserWindow BrowserWindow (facultatif)
• Objet options
  • title string (facultatif)
  • defaultPath string (facultatif)
  • buttonLabel string (facultatif) - Label personnalise pour le bouton de confirmation. Si il est laisse vide, le label par defaut sera utilise.
  • filters FileFilter[] (facultatif)
  • properties string[] (facultatif) - Contient les fonctionnalites que la boite de dialogue doit utiliser. Les valeurs suivantes sont prises en charge :
    • openFile - Permet la selection de fichiers.
    • openDirectory - Permet la selection de dossiers.
    • multiSelections - Permet la selection de multiples chemins.
    • showHiddenFiles - Affiche les fichiers caches dans la boite de dialogue.
    • createDirectory macOS - Permet la creation de nouveaux dossiers depuis la boite de dialogue.
    • promptToCreate Windows - Demande la creation du dossier si le chemin d'acces du fichier entre dans la boite de dialogue n'existe pas. Cela ne cree par reellement le fichier dans le chemin d'acces mais permet de donner des chemins d'acces inexistant devant etre crees par l'application.
    • noResolveAliases macOS - Desactive la resolution de l'alias automatique (lien symbolique) . Les alias selectionnes retourneront alors le chemin de l'alias au lieu de celui de leur cible.
    • treatPackageAsDirectory macOS - Considerer les paquets, tels que les dossiers .app , comme des dossiers plutot que des fichiers.
    • dontAddToRecent Windows - Ne pas ajouter l'element en cours d'ouverture a la liste des documents recents.
  • message string (facultatif) macOS - Message a afficher au-dessus des zones de saisie.
  • securityScopedBookmarks boolean (facultatif) macOS MAS - Permet la creation de securityScopedBookmarks lorsqu'ils sont empaquetes pour le Mac App Store.

Retourne Promise<Object> - Se resout avec un objet contenant les elements suivants :

• canceled booleen - Indique si la boite de dialogue a ete annulee ou non.
• filePaths string[] - Un tableau de chemins d'acces choisi par l'utilisateur. Si la boite de dialogue est annulee, ce sera un tableau vide.
• bookmarks string[] (facultatif) macOS MAS - Un tableau correspondant au tableau filePaths de chaines encodees en base64 qui contient des donnees de security scoped bookmark . Pour qu'il soit rempli, securityScopedBookmarks doit etre active. (Pour les valeurs de retour, voir la table ici .)

L'argument browserWindow permet a la boite de dialogue de se rattacher elle-meme a la fenetre parent, la rendant modale.

filters specifie un tableau de types de fichiers qui peuvent etre affiches ou selectionnes lorsque vous voulez limiter l'utilisateur a un type specifique. Par exemple :

{

  filtres
:
 [

    {
 name
 :
 'Images'
,
 extensions
:
 [
'jpg'
,
 'png'
,
 'gif'
]
 }
,

    {
 name
:
 'Films'
,
 extensions
:
 [
'mkv'
,
 'avi'
,
 'mp4'
]
 }
,

    {
 name
:
 'Type de fichier personnalise'
,
 extensions
:
 [
'as'
]
 }
,

    {
 name
:
 'Tous les fichiers'
,
 extensions
:
 [
'*'
]
 }

  ]

}

Le tableau d' extensions devra contenir les extensions sans caracteres generiques ou point (par exemple 'png' est correct, mais '.png' et '*.png' ne l'est pas). Pour afficher tous les fichiers, utilisez le caractere generique '*' (aucun autre caractere generique n'est pris en charge).

Remarque : Sur Windows et Linux, une boite de dialogue ne peux pas etre a la fois une selection de fichier et une selection de dossier, donc si vous definissez sur ces plateformes properties a ['openFile', 'openDirectory'] , c'est la selection de dossier qui s'affichera.

dialog
.
showOpenDialog
(
mainWindow
,
 {

  properties
:
 [
'openFile'
,
 'openDirectory'
]

}
)
.
then
(
result
 =>
 {

  console
.
log
(
result
.
canceled
)

  console
.
log
(
result
.
filePaths
)

}
)
.
catch
(
err
 =>
 {

  console
.
log
(
err
)

}
)

dialog.showSaveDialogSync([browserWindow, ]options) ?

• browserWindow BrowserWindow (facultatif)
• Objet options
  • title string (facultatif) - Titre de la boite de dialogue. Ne peut pas etre affiche sur certains environnements de bureau Linux .
  • defaultPath string (facultatif) - Chemin d'acces absolu, le chemin d'acces absolu du fichier, ou le nom du fichier a utiliser par defaut.
  • buttonLabel string (facultatif) - Label personnalise pour le bouton de confirmation. Si il est laisse vide, le label par defaut sera utilise.
  • filters FileFilter[] (facultatif)
  • message string (facultatif) macOS - Message a afficher au-dessus des champs de texte.
  • nameFieldLabel string (facultatif) macOS - Label personnalise pour le texte affiche devant le champ de texte du nom de fichier.
  • showsTagField boolean (facultatif) macOS - Affiche le champ de texte. true par defaut.
  • properties string[] (facultatif)
    • showHiddenFiles - Affiche les fichiers caches dans la boite de dialogue.
    • createDirectory macOS - Permet la creation de nouveaux dossiers depuis la boite de dialogue.
    • treatPackageAsDirectory macOS - Considerer les paquets, tels que les dossiers .app , comme des dossiers plutot que des fichiers.
    • showOverwriteConfirmation Linux - Definit si une boite de dialogue de confirmation sera affichee lorsque l’utilisateur tape un nom de fichier deja existant.
    • dontAddToRecent Windows - N'ajoutez pas l'element en cours d'ouverture a la liste des documents recents.
  • securityScopedBookmarks boolean (facultatif) macOS MAS - Creez un marque-page a portee de securite lorsque empaquete pour le Mac App Store. Si cette option est activee et que le fichier n'existe pas encore, un fichier vide sera cree dans le chemin choisi.

Retourne une string etant le chemin du fichier choisi par l'utilisateur ou une chaine vide si la boite de dialogue est annulee.

L'argument browserWindow permet a la boite de dialogue de s'attacher elle-meme a la fenetre parent, la rendant modale.

Les filters specifie un tableau de types de fichiers qui peuvent etre affiches, allez voir dialog.showOpenDialog pour un exemple.

dialog.showSaveDialog([browserWindow, ]options) ?

• browserWindow BrowserWindow (facultatif)
• Objet options
  • title string (facultatif) - Titre de la boite de dialogue. Ne peut pas etre affiche sur certains environnements de bureau Linux .
  • defaultPath string (facultatif) - Chemin d'acces absolu, le chemin d'acces absolu du fichier, ou le nom du fichier a utiliser par defaut.
  • buttonLabel string (facultatif) - Etiquette personnalisee pour le bouton de confirmation. Si laisse vide, l'etiquette par defaut sera utilise.
  • filters FileFilter[] (facultatif)
  • message string (facultatif) macOS - Message a afficher au-dessus des champs de texte.
  • nameFieldLabel string (facultatif) macOS - Etiquette personnalisee pour le texte affiche devant le champ de texte du nom de fichier.
  • showsTagField boolean (facultatif) macOS - Affiche le champ de texte, par defaut a true .
  • properties string[] (facultatif)
    • showHiddenFiles - Affiche les fichiers caches dans la boite de dialogue.
    • createDirectory macOS - Permet la creation de nouveaux dossiers depuis la boite de dialogue.
    • treatPackageAsDirectory macOS - Considerer les paquets, tels que les dossiers .app , comme des dossiers plutot que des fichiers.
    • showOverwriteConfirmation Linux - Definit si une boite de dialogue de confirmation sera affichee lorsque l’utilisateur tape un nom de fichier deja existant.
    • dontAddToRecent Windows - Ne pas ajouter l'element en cours d'ouverture a la liste des documents recents.
  • securityScopedBookmarks boolean (facultatif) macOS MAS - Cree un marque-page a portee de securite lorsque empaquete pour le Mac App Store. Si cette option est activee et que le fichier n'existe pas encore, un fichier vide sera cree dans le chemin choisi.

Retourne Promise<Object> - Qui se resout avec un objet contenant les elements suivants :

• canceled booleen - Indique si la boite de dialogue a ete annulee ou non.
• filePath string - sera undefined si la boite de dialogue est annulee, .
• bookmark string (facultatif) macOS MAS - Chaine codee en Base64 qui contient les donnees de signet etendues de securite pour le fichier enregistre. Mais pour cela securityScopedBookmarks doit etre active. (Pour les valeurs de retour, voir la table ici .)

L'argument browserWindow permet a la boite de dialogue de s'attacher elle-meme a la fenetre parent, la rendant modale.

Les filters specifie un tableau de types de fichiers qui peuvent etre affiches, allez voir dialog.showOpenDialog pour un exemple.

Remarque : Sur macOS, l'utilisation de la version asynchrone est recommandee pour eviter les problemes lorsque etend et reduit la boite de dialogue.

dialog.showMessageBoxSync([browserWindow, ]options) ?

• browserWindow BrowserWindow (facultatif)
• Objet options
  • message chaine - Contenu de la boite de message.
  • type string (facultatif) - Peut etre none , info , error , question ou warning . Sur Windows, question affiche la meme icone que info , sauf si vous definissez une autre en utilisant l'option icon . Sur macOS, warning et error affichent la meme icone d'avertissement.
  • boutons string[] (facultatif) - Tableau de textes pour les boutons. Sous Windows, un tableau vide entrainera un bouton intitule ≪?OK?≫.
  • defaultId Integer (facultatif) - Index du bouton dans le tableau des boutons qui seront selectionnes par defaut lorsque la boite de message s'ouvrira.
  • title string (facultatif) - Titre de la boite de message, certaines plateformes ne l'afficheront pas.
  • detail string (facultatif) - Informations supplementaires du message.
  • icon ( NativeImage | string) (facultatif)
  • textWidth Integer (facultatif) macOS - Largeur personnalisee du texte dans la boite de messages.
  • cancelId Integer (facultatif) - Index du bouton a utiliser pour annuler la boite de dialogue, via la touche Esc . Par defaut, ceci est assigne au premier bouton avec l'etiquette "annuler" ou "non". Si aucun bouton de ce type n'existe et que cette option n'est pas definie, 0 sera utilise comme valeur de retour .
  • noLink booleen (facultatif) - Sous Windows, Electron essaiera de determiner quels buttons sont des boutons courants (comme "Annuler" ou "Oui"), et affichera les autres comme liens de commande dans le dialog. Cela peut faire apparaitre la boite de dialogue dans le style des applications Windows modernes. Si vous n'aimez pas ce comportement, vous pouvez definir noLink a true .
  • normalizeAccessKeys boolean (facultatif) - Normalise les cles d'acces au clavier sur toutes les plateformes. Par defaut la valeur est false . Activer ceci suppose que & est utilise dans les libelles des boutons pour le placement de la touche d'acces du raccourci clavier et les libelles seront convertis pour qu'ils fonctionnent correctement sur chaque plateforme, le caractere & est supprime sur macOS, convertis en _ sous Linux, et conserve sur Windows. Par exemple, une etiquette de bouton de Vie&w sera converti en Vie_w sous Linux et Vie sous macOS et peut etre selectionne via Alt-W sur Windows et Linux.

Retourne Integer - l'index du bouton clique.

Affiche une boite de message, elle bloque le processus jusqu'a ce que la boite de message soit fermee. Retourne l'index du bouton clique.

L'argument browserWindow permet a la boite de dialogue de s'attacher elle-meme a la fenetre parent, la rendant modale. Si la browserWindow n’est pas affiche, la boite de dialogue n’y sera pas attachee. Dans ce cas, elle sera affiche comme une fenetre independante.

dialog.showMessageBox([browserWindow, ]options) ?

• browserWindow BrowserWindow (facultatif)
• Objet options
  • message chaine - Contenu de la boite de message.
  • type string (facultatif) - Peut etre none , info , error , question ou warning . Sur Windows, question affiche la meme icone que info , sauf si vous definissez une autre en utilisant l'option icon . Sur macOS, warning et error affichent la meme icone d'avertissement.
  • boutons string[] (facultatif) - Tableau de textes pour les boutons. Sous Windows, un tableau vide entrainera un bouton intitule ≪?OK?≫.
  • defaultId Integer (facultatif) - Index du bouton dans le tableau des boutons qui seront selectionnes par defaut lorsque la boite de message s'ouvrira.
  • signal AbortSignal (facultatif) - Passe une instance de AbortSignal pour eventuellement fermer la boite de message, celle-ci se comportera comme si elle avait ete annulee par l’utilisateur. Sur macOS, signal ne fonctionne pas avec les boites de messages qui n'ont pas de fenetre parente, car ces boites de messages s'executent de facon synchronisee en raison de limitations de la plate-forme.
  • title string (facultatif) - Titre de la boite de message, certaines plateformes ne l'afficheront pas.
  • detail string (facultatif) - Informations supplementaires du message.
  • checkboxLabel string (facultatif) - Si fourni, la case de message inclura une case a cocher avec l'etiquette donnee.
  • checkboxChecked boolean (facultatif) - Etat initial de la case a cocher. false par defaut.
  • icon ( NativeImage | string) (facultatif)
  • textWidth Integer(facultatif) macOS - Largeur personnalisee du texte dans la boite de message.
  • cancelId Integer (facultatif) - Iindex du bouton a utiliser pour annuler la boite de dialogue, via la touche Esc . Par defaut, ceci est assigne au premier bouton avec l'etiquette "annuler" ou "non". Si aucun bouton de ce type n'existe et que cette option n'est pas definie, 0 sera utilise comme valeur de retour .
  • noLink booleen (facultatif) - Sous Windows, Electron essaiera de determiner quels buttons sont des boutons courants (comme "Annuler" ou "Oui"), et affichera les autres comme liens de commande dans le dialog. Cela peut faire apparaitre la boite de dialogue dans le style des applications Windows modernes. Si vous n'aimez pas ce comportement, vous pouvez definir noLink a true .
  • normalizeAccessKeys boolean (facultatif) - Normalise les cles d'acces au clavier sur toutes les plateformes. Par defaut la valeur est false . Activer ceci suppose que & est utilise dans les libelles des boutons pour le placement de la touche d'acces du raccourci clavier et les libelles seront convertis pour qu'ils fonctionnent correctement sur chaque plateforme, le caractere & est supprime sur macOS, convertis en _ sous Linux, et conserve sur Windows. Par exemple, une etiquette de bouton de Vie&w sera converti en Vie_w sous Linux et Vie sous macOS et peut etre selectionne via Alt-W sur Windows et Linux.

Retourne Promise<Object> - resout avec une promesse contenant les proprietes suivantes :

• response number - Index du bouton qui a ete clique.
• checkboxChecked boolean - Etat coche de la case a cocher si checkboxLabel a ete defini. Sinon false .

Affichage d'une boite de message.

L'argument browserWindow permet a la boite de dialogue de s'attacher elle-meme a la fenetre parent, la rendant modale.

dialog.showErrorBox(title, content) ?

• title string - Le titre a afficher dans la boite d'erreur.
• content string - Le contenu du texte a afficher dans la boite d'erreur.

Affiche une boite de dialogue modale qui affiche un message d'erreur.

Cette API peut etre appelee en toute securite avant l'evenement ready que le module app emet, il est generalement utilise pour signaler des erreurs au debut du demarrage. Si appele avant l'application pret evenement sous Linux, le message sera emis sur stderr, et aucune fenetre GUI n'apparaitra.

dialog.showCertificateTrustDialog([browserWindow, ]options) macOS Windows ?

• browserWindow BrowserWindow (facultatif)
• Objet options
  • certificat certificat - Le certificat de confiance/importation.
  • message string - Le message a afficher a l'utilisateur.

Retourne Promise<void> - qui se resout lorsque la boite de dialogue de confiance du certificat est affichee.

Sur macOS, ceci affiche une boite de dialogue modale presentant un message, les informations du certificat et donnant a l'utilisateur la possibilite de se fier/importer le certificat. Si vous fournissez en argument une browserWindow , la boite de dialogue sera attachee a la fenetre parente, la rendant modale.

Sous Windows, les options sont plus limitees, en raison des API Win32 utilisees:

• L'argument message n'est pas utilise, car l'OS fournit sa propre boite de dialogue de confirmation.
• L'argument browserWindow est ignore car il n'est pas possible de rendre cette fenetre de confirmation modale.

Tableau des signets ?

showOpenDialog , showOpenDialogSync , showSaveDialog et showSaveDialogSync retourne un tableau de bookmarks .

Feuilles ?

Sur macOS, les dialogues sont presentes comme des feuilles attachees a une fenetre si vous fournissez une reference BrowserWindow dans le parametre browserWindow , ou modales si aucune fenetre n'est fournie.

Vous pouvez appeler BrowserWindow.getCurrentWindow().setSheetOffset(offset) pour changer le decalage depuis la fenetre ou les feuilles sont attachees.