Aller au contenu principal

dialog

Affiche des boîtes de dialogue système natives pour l’ouverture et l’enregistrement de fichiers, les alertes, etc.

Processus : Main

Par exemple: affichage d'une boîte de dialogue pour sélectionner plusieurs fichiers :

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

Méthodes​

Le module dialog dispose des méthodes suivantes :

dialog.showOpenDialogSync([browserWindow, ]options)​

  • browserWindow BrowserWindow (facultatif)
  • Objet options
    • title string (facultatif)
    • defaultPath string (facultatif)
    • buttonLabel string (facultatif) - Label personnalisé pour le bouton de confirmation. Si il est laissé vide, le label par défaut sera utilisé.
    • filters FileFilter[] (facultatif)
    • properties string[] (facultatif) - Contient les fonctionnalités que la boîte de dialogue doit utiliser. Les valeurs suivantes sont prises en charge :
      • openFile - Permet la sélection de fichiers.
      • openDirectory - Permet la sélection de dossiers.
      • multiSelections - Permet la sélection de multiples chemins.
      • showHiddenFiles - Affiche les fichiers cachés dans la boîte de dialogue.
      • createDirectory macOS - Permet la création de nouveaux dossiers depuis la boîte de dialogue.
      • promptToCreate Windows - Demande la création du dossier si le chemin d'accès du fichier entré dans la boîte de dialogue n'existe pas. Cela ne créer par réellement le fichier dans le chemin d'accès mais permet de donner des chemins d'accès inexistant qui devraient être créés par l'application.
      • noResolveAliases macOS - Désactive la résolution de l'alias automatique (lien symbolique) . Les alias sélectionnés retourneront alors le chemin de l'alias au lieu de celui de leur cible.
      • treatPackageAsDirectory macOS - Considérer les paquets, tels que les dossiers .app, comme des dossiers plutôt que des fichiers.
      • dontAddToRecent Windows - Ne pas ajouter l'élément en cours d'ouverture à la liste des documents récents.
    • message string (facultatif) macOS - Message à afficher au-dessus des zones de saisie.
    • securityScopedBookmarks boolean (facultatif) macOS MAS - Permet la création de securityScopedBookmarks lorsqu'ils sont empaquetés pour le Mac App Store.

Retourne string[] | undefined - le chemin du fichier choisi par l'utilisateur ; si la boîte de dialogue est annulée retourne undefined.

L'argument browserWindow permet à la boîte de dialogue de s'attacher elle-même à la fenêtre parent, la rendant modale.

filters spécifie un tableau de types de fichiers qui peuvent être affichés ou sélectionnés lorsque vous voulez limiter l'utilisateur à un type spécifique. Par exemple :

{
  filtres: [
    { name : 'Images', extensions: ['jpg', 'png', 'gif'] },
    { name: 'Films', extensions: ['mkv', 'avi', 'mp4'] },
    { name: 'Type de fichier personnalisé', extensions: ['as'] },
    { name: 'Tous les fichiers', extensions: ['*'] }
  ]
}

Le tableau d'extensions doit contenir des extensions sans caractères génériques ou de point (par exemple 'png' est correct, mais '.png' et '*.png' ne l'est pas). Pour afficher tous les fichiers, utilisez le caractère générique '*' (aucun autre caractère générique n'est pris en charge).

Remarque : Sur Windows et Linux, une boîte de dialogue ne peux pas être à la fois une sélection de fichier et une sélection de dossier, donc si vous définissez sur ces plateformes properties à ['openFile', 'openDirectory'], c'est la sélection de dossier qui s'affichera.

dialog.showOpenDialogSync(mainWindow, {
  propriétés: ['openFile', 'openDirectory']
})

dialog.showOpenDialog([browserWindow, ]options)​

  • browserWindow BrowserWindow (facultatif)
  • Objet options
    • title string (facultatif)
    • defaultPath string (facultatif)
    • buttonLabel string (facultatif) - Label personnalisé pour le bouton de confirmation. Si il est laissé vide, le label par défaut sera utilisé.
    • filters FileFilter[] (facultatif)
    • properties string[] (facultatif) - Contient les fonctionnalités que la boîte de dialogue doit utiliser. Les valeurs suivantes sont prises en charge :
      • openFile - Permet la sélection de fichiers.
      • openDirectory - Permet la sélection de dossiers.
      • multiSelections - Permet la sélection de multiples chemins.
      • showHiddenFiles - Affiche les fichiers cachés dans la boîte de dialogue.
      • createDirectory macOS - Permet la création de nouveaux dossiers depuis la boîte de dialogue.
      • promptToCreate Windows - Demande la création du dossier si le chemin d'accès du fichier entré dans la boîte de dialogue n'existe pas. Cela ne crée par réellement le fichier dans le chemin d'accès mais permet de donner des chemins d'accès inexistant devant être créés par l'application.
      • noResolveAliases macOS - Désactive la résolution de l'alias automatique (lien symbolique) . Les alias sélectionnés retourneront alors le chemin de l'alias au lieu de celui de leur cible.
      • treatPackageAsDirectory macOS - Considérer les paquets, tels que les dossiers .app, comme des dossiers plutôt que des fichiers.
      • dontAddToRecent Windows - Ne pas ajouter l'élément en cours d'ouverture à la liste des documents récents.
    • message string (facultatif) macOS - Message à afficher au-dessus des zones de saisie.
    • securityScopedBookmarks boolean (facultatif) macOS MAS - Permet la création de securityScopedBookmarks lorsqu'ils sont empaquetés pour le Mac App Store.

Retourne Promise<Object> - Se résout avec un objet contenant les éléments suivants :

  • canceled booléen - Indique si la boîte de dialogue a été annulée ou non.
  • filePaths string[] - Un tableau de chemins d'accès choisi par l'utilisateur. Si la boîte de dialogue est annulée, ce sera un tableau vide.
  • bookmarks string[] (facultatif) macOS MAS - Un tableau correspondant au tableau filePaths de chaînes encodées en base64 qui contient des données de security scoped bookmark. Pour qu'il soit rempli, securityScopedBookmarks doit être activé. (Pour les valeurs de retour, voir la table ici.)

L'argument browserWindow permet à la boîte de dialogue de se rattacher elle-même à la fenêtre parent, la rendant modale.

filters spécifie un tableau de types de fichiers qui peuvent être affichés ou sélectionnés lorsque vous voulez limiter l'utilisateur à un type spécifique. Par exemple :

{
  filtres: [
    { name : 'Images', extensions: ['jpg', 'png', 'gif'] },
    { name: 'Films', extensions: ['mkv', 'avi', 'mp4'] },
    { name: 'Type de fichier personnalisé', extensions: ['as'] },
    { name: 'Tous les fichiers', extensions: ['*'] }
  ]
}

Le tableau d'extensions devra contenir les extensions sans caractères génériques ou point (par exemple 'png' est correct, mais '.png' et '*.png' ne l'est pas). Pour afficher tous les fichiers, utilisez le caractère générique '*' (aucun autre caractère générique n'est pris en charge).

Remarque : Sur Windows et Linux, une boîte de dialogue ne peux pas être à la fois une sélection de fichier et une sélection de dossier, donc si vous définissez sur ces plateformes properties à ['openFile', 'openDirectory'], c'est la sélection 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 boîte de dialogue. Ne peut pas être affiché sur certains environnements de bureau Linux.
    • defaultPath string (facultatif) - Chemin d'accès absolu, le chemin d'accès absolu du fichier, ou le nom du fichier à utiliser par défaut.
    • buttonLabel string (facultatif) - Label personnalisé pour le bouton de confirmation. Si il est laissé vide, le label par défaut sera utilisé.
    • filters FileFilter[] (facultatif)
    • message string (facultatif) macOS - Message à afficher au-dessus des champs de texte.
    • nameFieldLabel string (facultatif) macOS - Label personnalisé pour le texte affiché devant le champ de texte du nom de fichier.
    • showsTagField boolean (facultatif) macOS - Affiche le champ de texte. true par défaut.
    • properties string[] (facultatif)
      • showHiddenFiles - Affiche les fichiers cachés dans la boîte de dialogue.
      • createDirectory macOS - Permet la création de nouveaux dossiers depuis la boîte de dialogue.
      • treatPackageAsDirectory macOS - Considérer les paquets, tels que les dossiers .app, comme des dossiers plutôt que des fichiers.
      • showOverwriteConfirmation Linux - Définit si une boîte de dialogue de confirmation sera affichée lorsque l’utilisateur tape un nom de fichier déjà existant.
      • dontAddToRecent Windows - N'ajoutez pas l'élément en cours d'ouverture à la liste des documents récents.
    • securityScopedBookmarks boolean (facultatif) macOS MAS - Créez un marque-page à portée de sécurité lorsque empaqueté pour le Mac App Store. Si cette option est activée et que le fichier n'existe pas encore, un fichier vide sera créé dans le chemin choisi.

Retourne string | undefined, le chemin du fichier choisi par l'utilisateur; retourne undefined si la boîte de dialogue est annulée.

L'argument browserWindow permet à la boîte de dialogue de s'attacher elle-même à la fenêtre parent, la rendant modale.

Les filters spécifie un tableau de types de fichiers qui peuvent être affichés, allez voir dialog.showOpenDialog pour un exemple.

dialog.showSaveDialog([browserWindow, ]options)​

  • browserWindow BrowserWindow (facultatif)
  • Objet options
    • title string (facultatif) - Titre de la boîte de dialogue. Ne peut pas être affiché sur certains environnements de bureau Linux.
    • defaultPath string (facultatif) - Chemin d'accès absolu, le chemin d'accès absolu du fichier, ou le nom du fichier à utiliser par défaut.
    • buttonLabel string (facultatif) - Étiquette personnalisée pour le bouton de confirmation. Si laissé vide, l'étiquette par défaut sera utilisé.
    • filters FileFilter[] (facultatif)
    • message string (facultatif) macOS - Message à afficher au-dessus des champs de texte.
    • nameFieldLabel string (facultatif) macOS - Étiquette personnalisée pour le texte affiché devant le champ de texte du nom de fichier.
    • showsTagField boolean (facultatif) macOS - Affiche le champ de texte, par défaut à true.
    • properties string[] (facultatif)
      • showHiddenFiles - Affiche les fichiers cachés dans la boîte de dialogue.
      • createDirectory macOS - Permet la création de nouveaux dossiers depuis la boîte de dialogue.
      • treatPackageAsDirectory macOS - Considérer les paquets, tels que les dossiers .app, comme des dossiers plutôt que des fichiers.
      • showOverwriteConfirmation Linux - Définit si une boîte de dialogue de confirmation sera affichée lorsque l’utilisateur tape un nom de fichier déjà existant.
      • dontAddToRecent Windows - Ne pas ajouter l'élément en cours d'ouverture à la liste des documents récents.
    • securityScopedBookmarks boolean (facultatif) macOS MAS - Crée un marque-page à portée de sécurité lorsque empaqueté pour le Mac App Store. Si cette option est activée et que le fichier n'existe pas encore, un fichier vide sera créé dans le chemin choisi.

Retourne Promise<Object> - Qui se résout avec un objet contenant les éléments suivants :

  • canceled booléen - Indique si la boîte de dialogue a été annulée ou non.
  • filePath string (facultatif) - Si la boîte de dialogue est annulée, ce sera undefined.
  • bookmark string (facultatif) macOS MAS - Chaîne codée en Base64 qui contient les données de signet étendues de sécurité pour le fichier enregistré. Mais pour cela securityScopedBookmarks doit être activé. (Pour les valeurs de retour, voir la table ici.)

L'argument browserWindow permet à la boîte de dialogue de s'attacher elle-même à la fenêtre parent, la rendant modale.

Les filters spécifie un tableau de types de fichiers qui peuvent être affichés, allez voir dialog.showOpenDialog pour un exemple.

Remarque : Sur macOS, l'utilisation de la version asynchrone est recommandée pour éviter les problèmes lorsque étend et réduit la boîte de dialogue.

dialog.showMessageBoxSync([browserWindow, ]options)​

  • browserWindow BrowserWindow (facultatif)
  • Objet options
    • message chaîne - Contenu de la boîte de message.
    • type string (facultatif) - Peut être none, info, error, question ou warning. Sur Windows, question affiche la même icône que info, sauf si vous définissez une autre en utilisant l'option icon. Sur macOS, warning et error affichent la même icône d'avertissement.
    • boutons string[] (facultatif) - Tableau de textes pour les boutons. Sous Windows, un tableau vide entraînera un bouton intitulé « OK ».
    • defaultId Integer (facultatif) - Index du bouton dans le tableau des boutons qui seront sélectionnés par défaut lorsque la boîte de message s'ouvrira.
    • title string (facultatif) - Titre de la boîte de message, certaines plateformes ne l'afficheront pas.
    • detail string (facultatif) - Informations supplémentaires du message.
    • icon (NativeImage | string) (facultatif)
    • textWidth Integer (facultatif) macOS - Largeur personnalisée du texte dans la boîte de messages.
    • cancelId Integer (facultatif) - Index du bouton à utiliser pour annuler la boîte de dialogue, via la touche Esc. Par défaut, ceci est assigné au premier bouton avec l'étiquette "annuler" ou "non". Si aucun bouton de ce type n'existe et que cette option n'est pas définie, 0 sera utilisé comme valeur de retour .
    • noLink booléen (facultatif) - Sous Windows, Electron essaiera de déterminer quels buttons sont des boutons courants (comme "Annuler" ou "Oui"), et affichera les autres comme liens de commande dans le dialog. Cela peut faire apparaître la boîte de dialogue dans le style des applications Windows modernes. Si vous n'aimez pas ce comportement, vous pouvez définir noLink à true.
    • normalizeAccessKeys boolean (facultatif) - Normalise les clés d'accès au clavier sur toutes les plateformes. Par défaut la valeur est false. Activer ceci suppose que & est utilisé dans les libellés des boutons pour le placement de la touche d'accès du raccourci clavier et les libellés seront convertis pour qu'ils fonctionnent correctement sur chaque plateforme, le caractère & est supprimé sur macOS, convertis en _ sous Linux, et conservé sur Windows. Par exemple, une étiquette de bouton de Vie&w sera converti en Vie_w sous Linux et Vie sous macOS et peut être sélectionné via Alt-W sur Windows et Linux.

Retourne Integer - l'index du bouton cliqué.

Affiche une boîte de message, elle bloque le processus jusqu'à ce que la boîte de message soit fermée. Retourne l'index du bouton cliqué.

L'argument browserWindow permet à la boîte de dialogue de s'attacher elle-même à la fenêtre parent, la rendant modale. Si la browserWindow n’est pas affiché, la boîte de dialogue n’y sera pas attachée. Dans ce cas, elle sera affiché comme une fenêtre indépendante.

dialog.showMessageBox([browserWindow, ]options)​

  • browserWindow BrowserWindow (facultatif)
  • Objet options
    • message chaîne - Contenu de la boîte de message.
    • type string (facultatif) - Peut être none, info, error, question ou warning. Sur Windows, question affiche la même icône que info, sauf si vous définissez une autre en utilisant l'option icon. Sur macOS, warning et error affichent la même icône d'avertissement.
    • boutons string[] (facultatif) - Tableau de textes pour les boutons. Sous Windows, un tableau vide entraînera un bouton intitulé « OK ».
    • defaultId Integer (facultatif) - Index du bouton dans le tableau des boutons qui seront sélectionnés par défaut lorsque la boîte de message s'ouvrira.
    • signal AbortSignal (facultatif) - Passe une instance de AbortSignal pour éventuellement fermer la boîte de message, celle-ci se comportera comme si elle avait été annulée par l’utilisateur. Sur macOS, signal ne fonctionne pas avec les boîtes de messages qui n'ont pas de fenêtre parente, car ces boîtes de messages s'exécutent de façon synchronisée en raison de limitations de la plate-forme.
    • title string (facultatif) - Titre de la boîte de message, certaines plateformes ne l'afficheront pas.
    • detail string (facultatif) - Informations supplémentaires du message.
    • checkboxLabel string (facultatif) - Si fourni, la case de message inclura une case à cocher avec l'étiquette donnée.
    • checkboxChecked boolean (facultatif) - Etat initial de la case à cocher. false par défaut.
    • icon (NativeImage | string) (facultatif)
    • textWidth Integer(facultatif) macOS - Largeur personnalisée du texte dans la boîte de message.
    • cancelId Integer (facultatif) - Iindex du bouton à utiliser pour annuler la boîte de dialogue, via la touche Esc. Par défaut, ceci est assigné au premier bouton avec l'étiquette "annuler" ou "non". Si aucun bouton de ce type n'existe et que cette option n'est pas définie, 0 sera utilisé comme valeur de retour .
    • noLink booléen (facultatif) - Sous Windows, Electron essaiera de déterminer quels buttons sont des boutons courants (comme "Annuler" ou "Oui"), et affichera les autres comme liens de commande dans le dialog. Cela peut faire apparaître la boîte de dialogue dans le style des applications Windows modernes. Si vous n'aimez pas ce comportement, vous pouvez définir noLink à true.
    • normalizeAccessKeys boolean (facultatif) - Normalise les clés d'accès au clavier sur toutes les plateformes. Par défaut la valeur est false. Activer ceci suppose que & est utilisé dans les libellés des boutons pour le placement de la touche d'accès du raccourci clavier et les libellés seront convertis pour qu'ils fonctionnent correctement sur chaque plateforme, le caractère & est supprimé sur macOS, convertis en _ sous Linux, et conservé sur Windows. Par exemple, une étiquette de bouton de Vie&w sera converti en Vie_w sous Linux et Vie sous macOS et peut être sélectionné via Alt-W sur Windows et Linux.

Retourne Promise<Object> - résout avec une promesse contenant les propriétés suivantes :

  • response number - Index du bouton qui a été cliqué.
  • checkboxChecked boolean - État coché de la case à cocher si checkboxLabel a été défini. Sinon false.

Affichage d'une boite de message.

L'argument browserWindow permet à la boîte de dialogue de s'attacher elle-même à la fenêtre parent, la rendant modale.

dialog.showErrorBox(title, content)​

  • title string - Le titre à afficher dans la boîte d'erreur.
  • content string - Le contenu du texte à afficher dans la boîte d'erreur.

Affiche une boîte de dialogue modale qui affiche un message d'erreur.

Cette API peut être appelée en toute sécurité avant l'évènement ready que le module app émet, il est généralement utilisé pour signaler des erreurs au début du démarrage. Si appelé avant l'application prêtévénement sous Linux, le message sera émis sur stderr, et aucune fenêtre GUI n'apparaîtra.

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

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

Retourne Promise<void> - qui se résout lorsque la boîte de dialogue de confiance du certificat est affichée.

Sur macOS, ceci affiche une boîte de dialogue modale présentant un message, les informations du certificat et donnant à l'utilisateur la possibilité de se fier/importer le certificat. Si vous fournissez en argument une browserWindow, la boîte de dialogue sera attachée à la fenêtre parente, la rendant modale.

Sous Windows, les options sont plus limitées, en raison des API Win32 utilisées:

  • L'argument message n'est pas utilisé, car l'OS fournit sa propre boîte de dialogue de confirmation.
  • L'argument browserWindow est ignoré car il n'est pas possible de rendre cette fenêtre de confirmation modale.

Tableau des signets​

showOpenDialog, showOpenDialogSync, showSaveDialoget showSaveDialogSync retourne un tableau de bookmarks .

Type de compilationsecurityScopedBookmarks booleanType de RetourValeur de retour
macOS masTrueSuccès['LONGBOOKMARKSTRING']
macOS masTrueErreur[''] (array de chaînes vides)
macOS masFalseNA[] (empty array)
non masanyNA[] (empty array)

Feuilles​

Sur macOS, les dialogues sont présentés comme des feuilles attachées à une fenêtre si vous fournissez une référence BrowserWindow dans le paramètre browserWindow, ou modales si aucune fenêtre n'est fournie.

Vous pouvez appeler BrowserWindow.getCurrentWindow().setSheetOffset(offset) pour changer le décalage depuis la fenêtre où les feuilles sont attachées.