En esta página

FileDialog QML Type

Un cuadro de diálogo de archivos. Más...

Import Statement: import QtQuick.Dialogs
Since: Qt 6.2
Inherits:

Dialog

Propiedades

Descripción detallada

El tipo FileDialog proporciona una API de QML para los cuadros de diálogo de archivos.

El tipo de cuadro de diálogo de archivos permite que los cuadros de diálogo reproduzcan el aspecto y el comportamiento nativos de la plataforma.

Para mostrar un cuadro de diálogo de archivos, se debe crear una instancia de `FileDialog`, establecer las propiedades deseadas y llamar a ` open()`. La propiedad ` currentFolder ` se puede utilizar para determinar la carpeta en la que se abre el cuadro de diálogo. Las propiedades « selectedFile » y « selectedFiles » se pueden utilizar para determinar qué archivo o archivos están seleccionados al abrirse el cuadro de diálogo, y también se actualizan cuando el usuario selecciona un archivo en el cuadro de diálogo y cuando se acepta la selección.

import QtCore
import QtQuick
import QtQuick.Controls
import QtQuick.Dialogs

ApplicationWindow {
    width: 640
    height: 480
    visible: true

    header: ToolBar {
        Button {
            text: qsTr("Choose Image...")
            onClicked: fileDialog.open()
        }
    }

    Image {
        id: image
        anchors.fill: parent
        fillMode: Image.PreserveAspectFit
    }

    FileDialog {
        id: fileDialog
        currentFolder: StandardPaths.standardLocations(StandardPaths.PicturesLocation)[0]
        onAccepted: image.source = selectedFile
    }
}

Disponibilidad

Actualmente, el cuadro de diálogo de archivos nativo de la plataforma está disponible en las siguientes plataformas:

  • Android
  • iOS
  • Linux (cuando se ejecuta con el tema de la plataforma GTK+)
  • macOS
  • Windows

Qt Quick Dialogs utiliza una implementación de « Qt Quick » como alternativa en aquellas plataformas que no dispongan de una implementación nativa.

Véase también FolderDialog y StandardPaths.

Documentación de propiedades

acceptLabel : string

Esta propiedad contiene el texto de la etiqueta que se muestra en el botón que permite cerrar el cuadro de diálogo.

Cuando se establece en una cadena vacía, se utiliza la etiqueta predeterminada de la plataforma subyacente. La etiqueta predeterminada suele ser « Open » o « Save », dependiendo de en qué « fileMode » se utilice el cuadro de diálogo.

El valor por defecto es una cadena vacía.

Véase también rejectLabel.

currentFolder : url

Esta propiedad indica la carpeta en la que se seleccionan los archivos. Se puede configurar para controlar el directorio inicial que se muestra al abrir el cuadro de diálogo.

Para seleccionar una carpeta, utiliza en su lugar « FolderDialog ».

defaultSuffix : string

Esta propiedad contiene una extensión que se añade a los archivos seleccionados que no tienen ninguna extensión especificada. La extensión se utiliza normalmente para indicar el tipo de archivo (por ejemplo, «txt» indica un archivo de texto).

Si el primer carácter es un punto ('.'), se elimina.

fileMode : enumeration

Esta propiedad contiene el modo del cuadro de diálogo.

Valores disponibles:

ConstanteDescripción
FileDialog.OpenFileEl cuadro de diálogo se utiliza para seleccionar un archivo existente (por defecto).
FileDialog.OpenFilesEl cuadro de diálogo se utiliza para seleccionar varios archivos existentes.
FileDialog.SaveFileEl cuadro de diálogo se utiliza para seleccionar cualquier archivo. No es necesario que el archivo exista.

nameFilters : list<string>

Esta propiedad contiene los filtros que restringen los tipos de archivos que se pueden seleccionar.

FileDialog {
    nameFilters: ["Text files (*.txt)", "HTML files (*.html *.htm)"]
}

Las distintas plataformas pueden restringir los archivos que se pueden seleccionar de diferentes maneras. Por ejemplo, macOS desactivará las entradas de archivos que no coincidan con los filtros, mientras que Windows las ocultará.

Nota: *.* no es un filtro portátil, ya que la suposición tradicional de que la extensión del archivo determina su tipo no es válida en todos los sistemas operativos. Es posible que haya un archivo sin punto en su nombre (por ejemplo, Makefile). En un cuadro de diálogo de archivos nativo de Windows, *.* coincidirá con dichos archivos, mientras que en otros tipos de cuadros de diálogo de archivos puede que no sea así. Por lo tanto, es mejor utilizar * si lo que se pretende es seleccionar cualquier archivo.

Véase también selectedNameFilter.

options : flags

Esta propiedad contiene las distintas opciones que influyen en el aspecto y el comportamiento del cuadro de diálogo.

Por defecto, todas las opciones están desactivadas.

Las opciones deben configurarse antes de mostrar el cuadro de diálogo. No se garantiza que configurarlas mientras el cuadro de diálogo está visible tenga un efecto inmediato en el mismo (dependiendo de la opción y de la plataforma).

Opciones disponibles:

ConstanteDescripción
FileDialog.DontResolveSymlinksNo resolver enlaces simbólicos en el cuadro de diálogo de archivos. Por defecto, los enlaces simbólicos se resuelven.
FileDialog.DontConfirmOverwriteNo solicitar confirmación si se selecciona un archivo ya existente. Por defecto, se solicita confirmación.
FileDialog.ReadOnlyIndica que el cuadro de diálogo no permite crear directorios.
FileDialog.HideNameFilterDetailsIndica si los detalles del filtro de nombres de archivo están ocultos o no.
FileDialog.DontUseNativeDialogObliga al cuadro de diálogo a utilizar una implementación rápida no nativa.

rejectLabel : string

Esta propiedad contiene el texto de la etiqueta que se muestra en el botón que cierra el cuadro de diálogo.

Si se establece en una cadena vacía, se utiliza la etiqueta predeterminada de la plataforma subyacente. La etiqueta predeterminada suele ser « Cancel ».

El valor por defecto es una cadena vacía.

Véase también « acceptLabel ».

selectedFile : url

Esta propiedad contiene el último archivo que se seleccionó en el cuadro de diálogo.

Se puede configurar para controlar el archivo que se selecciona al abrir el cuadro de diálogo.

Si hay varios archivos seleccionados, esta propiedad hace referencia al primer archivo.

El valor de esta propiedad se actualiza cada vez que el usuario selecciona un archivo en el cuadro de diálogo y cuando se acepta el cuadro de diálogo. Gestiona la señal ` accepted()` para obtener la selección final.

Véase también selectedFiles, accepted() y currentFolder.

selectedFiles : list<url>

Esta propiedad contiene los últimos archivos que se seleccionaron en el cuadro de diálogo.

El valor de esta propiedad se actualiza cada vez que el usuario selecciona archivos en el cuadro de diálogo y cuando se acepta el cuadro de diálogo. Gestiona la señal « accepted()» para obtener la selección final.

Véase también accepted() y currentFolder.

selectedNameFilter group

selectedNameFilter.extensions : list<string>

selectedNameFilter.globs : list<string>

selectedNameFilter.index : int

selectedNameFilter.name : string

Estas propiedades contienen el filtro de nombres seleccionado actualmente.

NombreDescripción
índice: intEsta propiedad determina qué « name filter » está seleccionado. El filtro especificado se selecciona al abrir el cuadro de diálogo. El valor se actualiza cuando el usuario selecciona otro filtro.
[solo lectura] nombre: cadenaEsta propiedad contiene el nombre del filtro seleccionado. En el ejemplo siguiente, el nombre del primer filtro es « "Text files" » y el del segundo es « "HTML files" ».
[solo lectura] extensiones: lista<cadena>Esta propiedad contiene la lista de extensiones del filtro seleccionado. En el ejemplo siguiente, la lista de extensiones del primer filtro es ["txt"] y la del segundo es ["html", "htm"].
[solo lectura] globs: lista<cadena>Esta propiedad contiene la lista de patrones globales del filtro seleccionado. En el ejemplo siguiente, la lista de patrones globales del primer filtro es ["*.txt"] y la del segundo es ["*.html", "*.htm"].

Esta propiedad resulta útil, por ejemplo, en combinación con la propiedad ` nameFilters ` de ` FolderListModel`.

FileDialog {
    id: fileDialog
    selectedNameFilter.index: 1
    nameFilters: ["Text files (*.txt)", "HTML files (*.html *.htm)"]
}

MyDocument {
    id: document
    fileType: fileDialog.selectedNameFilter.extensions[0]
}

Véase también nameFilters.

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.