Saltar al contenido principal

dialog

Muestra diálogos nativos del sistema para abrir y guardar archivos, alertas, etc.

Proceso: principal

Un ejemplo de mostrar un dialogo para seleccionar múltiples archivos:

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

Métodos​

El módulo dialogo tiene los siguientes métodos:

dialog.showOpenDialogSync([window, ]options)​

  • window BaseWindow (optional)
  • options Object
    • título cadena (opcional)
    • defaultPath cadena (optional)
    • buttonLabel cadena (optional) - Etiqueta predeterminada para el botón de confirmación, cuando esta se deja vacía la etiqueta predeterminada será usada.
    • filters FileFilter[] (optional)
    • properties string[] (optional) - Contains which features the dialog should use. Los siguientes valores son soportados:
      • openFile - Le permite a los archivos ser seleccionados.
      • openDirectory - Le permite a los directorios ser seleccionados.
      • multiSelections - Permite que varios caminos sean seleccionados.
      • showHiddenFiles - Muestra archivos ocultos en diálogo.
      • createDirectory macOS- Permite crear nuevos directorios a partir del diálogo.
      • promptToCreate Windows - Aviso para la creación si la ruta de fichero insertado en el diálogo no existe. Esto no crea realmente un archivo en el camino pero permite a caminos no existentes a regresar que deberían ser creados por la aplicación.
      • noResolveAliases macOS - Deshabilite la resolución automática de la ruta de alias (enlace simbólico). Los alias seleccionados ahora devolverán la ruta de alias en lugar de la ruta de destino.
      • treatPackageAsDirectory macOS - Trata paquetes como carpetas .app, como un directorio en vez de como un fichero.
      • dontAddToRecent Windows - No agregar el elemento que se esta abriendo a la lista de documentos recientes.
    • message cadena (opcional) macOS - Mensaje a mostrar encima de las cajas de entrada.
    • securityScopedBookmarks boolean (opcional) macOS MAS - Crear marcadores con ámbito de seguridad cuando es empaquetado para la Mac App Store.

Devuelve string[] | undefined, la ruta del archivo elegido por el usuario, si el diálogo es cancelado devuelve undefined.

El argumento de window permite el diálogo a adjuntarse a una ventana parental, haciéndola una modalidad.

The filters specifies an array of file types that can be displayed or selected when you want to limit the user to a specific type. Por ejemplo:

{
  filters: [
    { name: 'Images', extensions: ['jpg', 'png', 'gif'] },
    { name: 'Movies', extensions: ['mkv', 'avi', 'mp4'] },
    { name: 'Custom File Type', extensions: ['as'] },
    { name: 'All Files', extensions: ['*'] }
  ]
}

Los extensions arreglos deberían contener extensiones sin comodines o puntos (e.g. 'png' es bueno, pero '.png' y '*.png' son malos). Para mostrar todos los archivos, usa el '*' comodín (ningún otro comodín es compatible).

Nota: En Windows y Linux, un diálogo abierto no puede ser un selector de archivo y un selector de directorio a la vez, así que si estableces properties a el ['openFile', 'openDirectory'] en estas plataformas, un selector de directorio.

dialog.showOpenDialogSync(mainWindow, {
  properties: ['openFile', 'openDirectory']
})

dialog.showOpenDialog([window, ]options)​

  • window BaseWindow (optional)
  • options Object
    • título cadena (opcional)
    • defaultPath cadena (optional)
    • buttonLabel cadena (optional) - Etiqueta predeterminada para el botón de confirmación, cuando esta se deja vacía la etiqueta predeterminada será usada.
    • filters FileFilter[] (optional)
    • properties string[] (optional) - Contains which features the dialog should use. Los siguientes valores son soportados:
      • openFile - Le permite a los archivos ser seleccionados.
      • openDirectory - Le permite a los directorios ser seleccionados.
      • multiSelections - Permite que varios caminos sean seleccionados.
      • showHiddenFiles - Muestra archivos ocultos en diálogo.
      • createDirectory macOS- Permite crear nuevos directorios a partir del diálogo.
      • promptToCreate Windows - Aviso para la creación si la ruta de fichero insertado en el diálogo no existe. Esto no crea realmente un archivo en el camino pero permite a caminos no existentes a regresar que deberían ser creados por la aplicación.
      • noResolveAliases macOS - Deshabilite la resolución automática de la ruta de alias (enlace simbólico). Los alias seleccionados ahora devolverán la ruta de alias en lugar de la ruta de destino.
      • treatPackageAsDirectory macOS - Trata paquetes como carpetas .app, como un directorio en vez de como un fichero.
      • dontAddToRecent Windows - No agregar el elemento que se esta abriendo a la lista de documentos recientes.
    • message cadena (opcional) macOS - Mensaje a mostrar encima de las cajas de entrada.
    • securityScopedBookmarks boolean (opcional) macOS MAS - Crear marcadores con ámbito de seguridad cuando es empaquetado para la Mac App Store.

Devuelve Promise<Object> - Resuelve con un objeto conteniendo lo siguiente:

  • canceled boolean - si el diálogo fue o no cancelado.
  • filePaths cadena[] - Un arreglo del camino de archivos elegido por el usuario. Si es dialog es cancelado esto será un array vacío.
  • bookmarks string[] (optional) macOS MAS - An array matching the filePaths array of base64 encoded strings which contains security scoped bookmark data. securityScopedBookmarks debe estar activado para ser poblado. (Para devolver valores, vea tabla aquí.)

El argumento de window permite el diálogo a adjuntarse a una ventana parental, haciéndola una modalidad.

The filters specifies an array of file types that can be displayed or selected when you want to limit the user to a specific type. Por ejemplo:

{
  filters: [
    { name: 'Images', extensions: ['jpg', 'png', 'gif'] },
    { name: 'Movies', extensions: ['mkv', 'avi', 'mp4'] },
    { name: 'Custom File Type', extensions: ['as'] },
    { name: 'All Files', extensions: ['*'] }
  ]
}

Los extensions arreglos deberían contener extensiones sin comodines o puntos (e.g. 'png' es bueno, pero '.png' y '*.png' son malos). Para mostrar todos los archivos, usa el '*' comodín (ningún otro comodín es compatible).

Nota: En Windows y Linux, un diálogo abierto no puede ser un selector de archivo y un selector de directorio a la vez, así que si estableces properties a el ['openFile', 'openDirectory'] en estas plataformas, un selector de directorio.

dialog.showOpenDialog(mainWindow, {
  properties: ['openFile', 'openDirectory']
}).then(result => {
  console.log(result.canceled)
  console.log(result.filePaths)
}).catch(err => {
  console.log(err)
})

dialog.showSaveDialogSync([window, ]options)​

  • window BaseWindow (optional)
  • options Object
    • title cadena (opcional) - Título del diálogo. No puede mostrarse en algunos entornos de escritorio de Linux.
    • defaultPath cadena (opcional) - El camino de directorio absoluto, el camino de archivo absoluto o el nombre del archivo a usar por defecto.
    • buttonLabel cadena (optional) - Etiqueta predeterminada para el botón de confirmación, cuando esta se deja vacía la etiqueta predeterminada será usada.
    • filters FileFilter[] (optional)
    • message cadena (opcional) macOS - Mensaje a mostrar por encima de los campos de texto.
    • nameFieldLabel cadena (opcional) macOS - Etiqueta personalizada para el texto mostrado en frente al nombre del archivo del campo de texto.
    • showsTagField boolean (opcional) macOS - Muestra las etiquetas de las cajas de entrada, por defecto a true.
    • properties string[] (optional)
      • showHiddenFiles - Muestra archivos ocultos en diálogo.
      • createDirectory macOS- Permite crear nuevos directorios a partir del diálogo.
      • treatPackageAsDirectory macOS - Trata paquetes como carpetas .app, como un directorio en vez de como un fichero.
      • showOverwriteConfirmation Linux - Establece si al usuario será presentado un dialogo de confirmación si escribe el nombre de un archivo que ya existe.
      • dontAddToRecent Windows - No añadir el elemento que se está guardando en la lista de documentos recientes.
    • securityScopedBookmarks boolean (opcional) macOS MAS - Crear un security scoped bookmark es empaquetado para el Mac App Store. Si esta opción está activada y el fichero no existe todavía, se creará un fichero en blanco en la carpeta seleccionada.

Devuelve string, la ruta del archivo elegido por el usuario; si el cuadro de diálogo es cancelado retorna un string vacío.

El argumento de window permite el diálogo a adjuntarse a una ventana parental, haciéndola una modalidad.

Los filtros especifican un arreglo de los tipos de archivos can pueden ser mostrados, ver dialog.showOpenDialog por un ejemplo.

dialog.showSaveDialog([window, ]options)​

  • window BaseWindow (optional)
  • options Object
    • title cadena (opcional) - Título del diálogo. No puede mostrarse en algunos entornos de escritorio de Linux.
    • defaultPath cadena (opcional) - El camino de directorio absoluto, el camino de archivo absoluto o el nombre del archivo a usar por defecto.
    • buttonLabel cadena (optional) - Etiqueta predeterminada para el botón de confirmación, cuando esta se deja vacía la etiqueta predeterminada será usada.
    • filters FileFilter[] (optional)
    • message cadena (opcional) macOS - Mensaje a mostrar por encima de los campos de texto.
    • nameFieldLabel cadena (opcional) macOS - Etiqueta personalizada para el texto mostrado en frente al nombre del archivo del campo de texto.
    • showsTagField boolean (opcional) macOS - Muestra las etiquetas input box, por defecto true.
    • properties string[] (optional)
      • showHiddenFiles - Muestra archivos ocultos en diálogo.
      • createDirectory macOS- Permite crear nuevos directorios a partir del diálogo.
      • treatPackageAsDirectory macOS - Trata paquetes como carpetas .app, como un directorio en vez de como un fichero.
      • showOverwriteConfirmation Linux - Establece si al usuario será presentado un dialogo de confirmación si escribe el nombre de un archivo que ya existe.
      • dontAddToRecent Windows - No añadir el elemento que se está guardando en la lista de documentos recientes.
    • securityScopedBookmarks boolean (opcional) macOS MAS - Crear un security scoped bookmark es empaquetado para el Mac App Store. Si esta opción está activada y el fichero no existe todavía, se creará un fichero en blanco en la carpeta seleccionada.

Devuelve Promise<Object> - Resuelve con un objeto conteniendo lo siguiente:

  • canceled boolean - si el diálogo fue o no cancelado.
  • filePath string - Si el cuadro de diálogo es cancelado, se convertirá en un string vacío.
  • bookmark string (opcional) macOS MAS - Cadena codificada en Base64 que contiene los datos del marcador con ámbito de seguridad para el archivo guardado. securityScopedBookmarks deben estar activados para estar presentes. (Para devolver valores, vea tabla aquí.)

El argumento de window permite el diálogo a adjuntarse a una ventana parental, haciéndola una modalidad.

Los filtros especifican un arreglo de los tipos de archivos can pueden ser mostrados, ver dialog.showOpenDialog por un ejemplo.

Nota: En macOS, se recomienda usar la versión asincrona para evitar problemas cuando expanda y colapsa el diálogo.

dialog.showMessageBoxSync([wndow, ]options)​

  • window BaseWindow (optional)
  • options Object
    • message cadena - Contenido de la caja de mensaje.
    • type cadena (opcional) - Puede ser none, info, error, question o warning. En Windows, question muestra el mismo icono que info, a menos que tu dispongas un icono usando la opción icon. En macOS, tanto warning como error muestran el mismo icono de peligro.
    • buttons string[] (optional) - Array of texts for buttons. En Windows, un array vacío resultará en un botón con al etiqueta "OK".
    • defaultId Íntegro (opcional) - El índice del botón en el arreglo de los botones, el cual será selecto por defecto cuando el mensaje de la caja se abra.
    • title cadena (opcional) - Título del mensaje de la caja, algunas plataformas no se mostrarán.
    • detail cadena (opcional) - Información extra del mensaje.
    • icon (NativeImage | string) (optional)
    • textWidth Integer (opcional) macOS - Ancho personalizado del texto en el cuadro de mensaje.
    • cancelId Íntegro (opcional) - El índice el botón a ser usado a cancelar el diálogo, por vía la llave Esc. Por defecto, esto es asignado a el primer botón con "cancelar" o "no" como una etiqueta. Si no existen tales botones etiquetados y esta opción no esta configurada, 0 será usada como el valor de retorno.
    • noLink boolean (opcional) - En Windows Electron se tratará de averiguar cuál de los buttons son botones comunes (como "Cancelar" o "Sí"), y muestra los otros como links de comandos en el diálogo. Esto puede hacer que el diálogo aparezca en el estilo de las aplicaciones modernas de Windows. Si no te gusta este comportamiento, puedes establecer noLink a true.
    • normalizeAccessKeys boolean (opcional) - Normalizar el acceso al teclado a través de las plataformas. Por defecto es false. Permitir esto asume que & es usado en las etiquetas de los botones para el colocamiento de los atajos de acceso de las teclas del teclado y las etiquetas serán convertidas para que funcionen correctamente en cada plataforma, & personajes serán eliminados de macOS, convertidos a _ en Linux, y dejado intacto en Windows. Por ejemplo, una etiqueta de botón de Vie&w será convertida a Vie_w en Linux y View en macOS y puede ser seleccionado vía Alt-W en Windows y Linux.

Devuelve Integer - el índice del botón pulsado.

Muestra un cuadro de mensaje, bloqueará el proceso hasta que el cuadro de mensaje esté cerrado. Devuelve el indice del botón pulsado.

El argumento de window permite el diálogo a adjuntarse a una ventana parental, haciéndola una modalidad. Si window no es mostrado no se le adjuntará el dialog. In such case it will be displayed as an independent window.

dialog.showMessageBox([window, ]options)​

  • window BaseWindow (optional)
  • options Object
    • message cadena - Contenido de la caja de mensaje.
    • type cadena (opcional) - Puede ser none, info, error, question o warning. En Windows, question muestra el mismo icono que info, a menos que tu dispongas un icono usando la opción icon. En macOS, tanto warning como error muestran el mismo icono de peligro.
    • buttons string[] (optional) - Array of texts for buttons. En Windows, un array vacío resultará en un botón con al etiqueta "OK".
    • defaultId Íntegro (opcional) - El índice del botón en el arreglo de los botones, el cual será selecto por defecto cuando el mensaje de la caja se abra.
    • signal AbortSignal (opcional) - Pasar un instancia de AbortSignal a opcionalmente cerrar el cuadro de mensaje, el cuadro de mensaje se comportará como si fuera cancelado por el usuario. En macOS, signal no funciona con los cuadros de mensajes que no tengan una ventana padre, dado que esos cuadros de mensajes se ejecutan de forma sincrónica debido a las limitaciones de la plataforma.
    • title cadena (opcional) - Título del mensaje de la caja, algunas plataformas no se mostrarán.
    • detail cadena (opcional) - Información extra del mensaje.
    • checkboxLabel string (opcional) - Si se proporciona, el cuadro de mensaje será incluido como un checkbox con la etiqueta dada.
    • checkboxChecked boolean (opcional) - Estado inicial checked del checkbox. false por defecto.
    • icon (NativeImage | string) (optional)
    • textWidth Integer (opcional) macOS - Ancho personalizado del texto en el cuadro de mensaje.
    • cancelId Íntegro (opcional) - El índice el botón a ser usado a cancelar el diálogo, por vía la llave Esc. Por defecto, esto es asignado a el primer botón con "cancelar" o "no" como una etiqueta. Si no existen tales botones etiquetados y esta opción no esta configurada, 0 será usada como el valor de retorno.
    • noLink boolean (opcional) - En Windows Electron se tratará de averiguar cuál de los buttons son botones comunes (como "Cancelar" o "Sí"), y muestra los otros como links de comandos en el diálogo. Esto puede hacer que el diálogo aparezca en el estilo de las aplicaciones modernas de Windows. Si no te gusta este comportamiento, puedes establecer noLink a true.
    • normalizeAccessKeys boolean (opcional) - Normalizar el acceso al teclado a través de las plataformas. Por defecto es false. Permitir esto asume que & es usado en las etiquetas de los botones para el colocamiento de los atajos de acceso de las teclas del teclado y las etiquetas serán convertidas para que funcionen correctamente en cada plataforma, & personajes serán eliminados de macOS, convertidos a _ en Linux, y dejado intacto en Windows. Por ejemplo, una etiqueta de botón de Vie&w será convertida a Vie_w en Linux y View en macOS y puede ser seleccionado vía Alt-W en Windows y Linux.

Devuelve Promise<Object> - resuelve con una promesa conteniendo lo siguiente:

  • response number - El índice del botón pulsado.
  • checkboxChecked boolean - El estado checked state del checkbox si checkboxLabel fue establecido. De lo contrario false.

Shows a message box.

El argumento de window permite el diálogo a adjuntarse a una ventana parental, haciéndola una modalidad.

dialog.showErrorBox(title, content)​

  • title cadena - El título a mostrar en la caja de error.
  • content cadena - El texto contiene a mostrar en la caja de error.

Muestra un diálogo de modalidad que muestra un error de mensaje.

Esta API puede ser llamada seguramente antes que el evento ready el módulo app emite, es usualmente usado a reportar errores en las etapas tempranas del inicio. Si llamado antes de la aplicación ready evento en Linux, el mensaje será emitido a stderr, y no aparecerá diálogo GUI.

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

  • window BaseWindow (optional)
  • options Object
    • certificate Certificate - The certificate to trust/import.
    • message cadena - El mensaje a mostrar al usuario.

Devuelve Promise<void> - resuelve cuando se muestra el diálogo de confianza del certificado.

En macOS, esto muestra un diálogo modelo que muestra un mensaje e información certificada, y da al usuario la opción de confiar/importar el certificado. Si tú provees un argumento window el diálogo será adjuntado a la ventana parental, haciéndolo un modelo.

En Windows, las opciones son más limitadas, debido a que el Win32 APIs usado:

  • El argumento message no es usado, como el OS provee su propio diálogo de confirmación.
  • El argumento window es ignorado ya que no es posible hacer este diálogo modelo de confirmación.

Array de marcadores​

showOpenDialog, showOpenDialogSync, showSaveDialog, y showSaveDialogSync retornarán un array bookmarks.

Tipo de compilaciónsecurityScopedBookmarks booleanTipo de RetornoValor de Retorno
macOS masTrueÉxito['LONGBOOKMARKSTRING']
macOS masTrueError[''] (array de cadena vacía)
macOS masFalseNA[] (array vacío)
no mascualquieraNA[] (array vacío)

Páginas​

On macOS, dialogs are presented as sheets attached to a window if you provide a BaseWindow reference in the window parameter, or modals if no window is provided.

Puedes llamar a BaseWindow.getCurrentWindow().setSheetOffset(offset) para cambiar el offset del cuadro de la ventana en donde las páginas fueron adjuntadas.