En esta página

QFileSystemModel Class

La clase `QFileSystemModel` proporciona un modelo de datos para el sistema de archivos local. Más información...

Encabezado: #include <QFileSystemModel>
CMake: find_package(Qt6 REQUIRED COMPONENTS Gui)
target_link_libraries(mytarget PRIVATE Qt6::Gui)
qmake: QT += gui
Heredado de: QAbstractItemModel

Tipos públicos

enum Option { DontWatchForChanges, DontResolveSymlinks, DontUseCustomDirectoryIcons }
flags Options
enum Roles { FileIconRole, FilePathRole, FileNameRole, FilePermissions, FileInfoRole }

Propiedades

Funciones públicas

QFileSystemModel(QObject *parent = nullptr)
virtual ~QFileSystemModel()
QIcon fileIcon(const QModelIndex &index) const
QFileInfo fileInfo(const QModelIndex &index) const
QString fileName(const QModelIndex &index) const
QString filePath(const QModelIndex &index) const
QDir::Filters filter() const
QAbstractFileIconProvider *iconProvider() const
QModelIndex index(const QString &path, int column = 0) const
bool isDir(const QModelIndex &index) const
bool isReadOnly() const
QDateTime lastModified(const QModelIndex &index) const
(since 6.6) QDateTime lastModified(const QModelIndex &index, const QTimeZone &tz) const
QModelIndex mkdir(const QModelIndex &parent, const QString &name)
QVariant myComputer(int role = Qt::DisplayRole) const
bool nameFilterDisables() const
QStringList nameFilters() const
QFileSystemModel::Options options() const
QFileDevice::Permissions permissions(const QModelIndex &index) const
bool remove(const QModelIndex &index)
bool resolveSymlinks() const
bool rmdir(const QModelIndex &index)
QDir rootDirectory() const
QString rootPath() const
void setFilter(QDir::Filters filters)
void setIconProvider(QAbstractFileIconProvider *provider)
void setNameFilterDisables(bool enable)
void setNameFilters(const QStringList &filters)
void setOption(QFileSystemModel::Option option, bool on = true)
void setOptions(QFileSystemModel::Options options)
void setReadOnly(bool enable)
void setResolveSymlinks(bool enable)
QModelIndex setRootPath(const QString &newPath)
qint64 size(const QModelIndex &index) const
bool testOption(QFileSystemModel::Option option) const
QString type(const QModelIndex &index) const

Funciones públicas reimplementadas

virtual bool canFetchMore(const QModelIndex &parent) const override
virtual int columnCount(const QModelIndex &parent = QModelIndex()) const override
virtual QVariant data(const QModelIndex &index, int role = Qt::DisplayRole) const override
virtual bool dropMimeData(const QMimeData *data, Qt::DropAction action, int row, int column, const QModelIndex &parent) override
virtual void fetchMore(const QModelIndex &parent) override
virtual Qt::ItemFlags flags(const QModelIndex &index) const override
virtual bool hasChildren(const QModelIndex &parent = QModelIndex()) const override
virtual QVariant headerData(int section, Qt::Orientation orientation, int role = Qt::DisplayRole) const override
virtual QModelIndex index(int row, int column, const QModelIndex &parent = QModelIndex()) const override
virtual QMimeData *mimeData(const QModelIndexList &indexes) const override
virtual QStringList mimeTypes() const override
virtual QModelIndex parent(const QModelIndex &index) const override
virtual QHash<int, QByteArray> roleNames() const override
virtual int rowCount(const QModelIndex &parent = QModelIndex()) const override
virtual bool setData(const QModelIndex &idx, const QVariant &value, int role = Qt::EditRole) override
virtual QModelIndex sibling(int row, int column, const QModelIndex &idx) const override
virtual void sort(int column, Qt::SortOrder order = Qt::AscendingOrder) override
virtual Qt::DropActions supportedDropActions() const override

Señales

void directoryLoaded(const QString &path)
void fileRenamed(const QString &path, const QString &oldName, const QString &newName)
void rootPathChanged(const QString &newPath)

Funciones protegidas reimplementadas

virtual bool event(QEvent *event) override
virtual void timerEvent(QTimerEvent *event) override

Descripción detallada

Esta clase permite acceder al sistema de archivos local y ofrece funciones para renombrar y eliminar archivos y directorios, así como para crear nuevos directorios. En el caso más sencillo, se puede utilizar con un widget de visualización adecuado como parte de un navegador o un filtro.

Se puede acceder a `QFileSystemModel` mediante la interfaz estándar proporcionada por ` QAbstractItemModel`, pero también ofrece algunas funciones de conveniencia específicas de un modelo de directorios. Las funciones ` fileInfo()`, ` isDir()`, ` fileName()` y ` filePath()` proporcionan información sobre los archivos y directorios subyacentes relacionados con los elementos del modelo. Los directorios se pueden crear y eliminar mediante ` mkdir()` y ` rmdir()`.

Ejemplo de uso

Un modelo de directorios que muestra el contenido de un directorio predeterminado suele construirse con un objeto padre:

QFileSystemModel *model = new QFileSystemModel;
model->setRootPath(QDir::currentPath());

Se puede utilizar una vista de árbol para mostrar el contenido del modelo

QTreeView *tree = new QTreeView(splitter);
tree->setModel(model);

y el contenido de un directorio concreto se puede mostrar estableciendo el índice raíz de la vista de árbol:

tree->setRootIndex(model->index(QDir::currentPath()));

El índice raíz de la vista puede utilizarse para controlar qué parte de un modelo jerárquico se muestra. QFileSystemModel proporciona una función práctica que devuelve un índice de modelo adecuado para una ruta a un directorio dentro del modelo.

Almacenamiento en caché y rendimiento

QFileSystemModel utiliza un hilo independiente para rellenarse, por lo que no provocará que el hilo principal se cuelgue mientras se consulta el sistema de archivos. Las llamadas a rowCount() devolverán un valor de « 0 » hasta que el modelo rellene un directorio. El hilo en el que reside QFileSystemModel necesita ejecutar un bucle de eventos para procesar los datos entrantes.

QFileSystemModel no comenzará a rellenarse hasta que se llame a setRootPath(). Esto evita cualquier consulta innecesaria al sistema de archivos raíz del sistema, como la enumeración de unidades en Windows, hasta ese momento.

QFileSystemModel mantiene una caché con información sobre los archivos. La caché se mantiene actualizada automáticamente mediante el método QFileSystemWatcher.

Véase también Clases de modelo.

Documentación sobre los tipos de miembros

enum QFileSystemModel::Option
flags QFileSystemModel::Options

ConstanteValorDescripción
QFileSystemModel::DontWatchForChanges0x00000001No añadas observadores de archivos a las rutas. Esto reduce la sobrecarga al utilizar el modelo para tareas sencillas, como la finalización de la edición de líneas.
QFileSystemModel::DontResolveSymlinks0x00000002No resolver enlaces simbólicos en el modelo del sistema de archivos. Por defecto, los enlaces simbólicos se resuelven.
QFileSystemModel::DontUseCustomDirectoryIcons0x00000004Utiliza siempre el icono de directorio predeterminado. Algunas plataformas permiten al usuario establecer un icono diferente. La búsqueda de iconos personalizados provoca un gran impacto en el rendimiento en redes o unidades extraíbles. Esto establece la opción QFileIconProvider::DontUseCustomDirectoryIcons en el proveedor de iconos según corresponda.

El tipo Options es un typedef para QFlags<Option>. Almacena una combinación OR de valores de Option.

Véase también resolveSymlinks.

enum QFileSystemModel::Roles

ConstanteValorDescripción
QFileSystemModel::FileIconRoleQt::DecorationRole 
QFileSystemModel::FilePathRoleQt::UserRole + 1 
QFileSystemModel::FileNameRoleQt::UserRole + 2 
QFileSystemModel::FilePermissionsQt::UserRole + 3 
QFileSystemModel::FileInfoRoleQt::FileInfoRoleEl objeto « QFileInfo » para el índice

Documentación de propiedades

nameFilterDisables : bool

Esta propiedad determina si los archivos que no superan el filtro de nombre se ocultan o se desactivan

Esta propiedad está e true ada de forma predeterminada

Funciones de acceso:

bool nameFilterDisables() const
void setNameFilterDisables(bool enable)

options : Options

Esta propiedad contiene las distintas opciones que afectan al modelo

Por defecto, todas las opciones están desactivadas.

Las opciones deben configurarse antes de modificar las propiedades.

Funciones de acceso:

QFileSystemModel::Options options() const
void setOptions(QFileSystemModel::Options options)

Véase también setOption() y testOption().

readOnly : bool

Esta propiedad indica si el modelo de directorios permite escribir en el sistema de archivos

Si esta propiedad se establece en «false», el modelo de directorios permitirá renombrar, copiar y eliminar archivos y directorios.

Esta propiedad está e true e de forma predeterminada

Funciones de acceso:

bool isReadOnly() const
void setReadOnly(bool enable)

Esta propiedad determina si el modelo de directorios debe resolver los enlaces simbólicos

Esto solo es relevante en Windows.

Por defecto, esta propiedad está e true.

Funciones de acceso:

bool resolveSymlinks() const
void setResolveSymlinks(bool enable)

Véase también QFileSystemModel::Options.

Documentación de las funciones de miembro

[explicit] QFileSystemModel::QFileSystemModel(QObject *parent = nullptr)

Crea un modelo de sistema de archivos con el parent proporcionado.

[virtual noexcept] QFileSystemModel::~QFileSystemModel()

Elimina este modelo de sistema de archivos.

[override virtual] bool QFileSystemModel::canFetchMore(const QModelIndex &parent) const

Reimplementa: ` QAbstractItemModel::canFetchMore(const QModelIndex &parent) const`.

[override virtual] int QFileSystemModel::columnCount(const QModelIndex &parent = QModelIndex()) const

Reimplementa: ` QAbstractItemModel::columnCount(const QModelIndex &parent) const`.

[override virtual] QVariant QFileSystemModel::data(const QModelIndex &index, int role = Qt::DisplayRole) const

Reimplementa: ` QAbstractItemModel::data(const QModelIndex &index, int role) const`.

Véase también setData().

[signal] void QFileSystemModel::directoryLoaded(const QString &path)

Esta señal se emite cuando el hilo recopilador ha terminado de cargar el path.

[override virtual] bool QFileSystemModel::dropMimeData(const QMimeData *data, Qt::DropAction action, int row, int column, const QModelIndex &parent)

Reimplementa: QAbstractItemModel::dropMimeData(const QMimeData *data, Qt::DropAction action, int row, int column, const QModelIndex &parent).

Gestiona el objeto ` data ` proporcionado por una operación de arrastrar y soltar que ha finalizado con el ` action ` dado sobre la fila del modelo especificada por ` row ` y ` column `, así como por el índice ` parent `. Devuelve `true` si la operación se ha realizado correctamente.

Véase también supportedDropActions().

[override virtual protected] bool QFileSystemModel::event(QEvent *event)

Reimplementa: QObject::event(QEvent *e).

[override virtual] void QFileSystemModel::fetchMore(const QModelIndex &parent)

Reimplementa: ` QAbstractItemModel::fetchMore(const QModelIndex &parent)`.

QIcon QFileSystemModel::fileIcon(const QModelIndex &index) const

Devuelve el icono del elemento almacenado en el modelo bajo el nombre « index » indicado.

QFileInfo QFileSystemModel::fileInfo(const QModelIndex &index) const

Devuelve el objeto ` QFileInfo ` correspondiente al elemento almacenado en el modelo bajo el ` index` indicado.

QString QFileSystemModel::fileName(const QModelIndex &index) const

Devuelve el nombre del archivo correspondiente al elemento almacenado en el modelo en la ruta « index » indicada.

QString QFileSystemModel::filePath(const QModelIndex &index) const

Devuelve la ruta del elemento almacenado en el modelo bajo el « index » indicado.

[signal] void QFileSystemModel::fileRenamed(const QString &path, const QString &oldName, const QString &newName)

Esta señal se emite cada vez que un archivo con el nombre « oldName » se renombra correctamente a « newName ». El archivo se encuentra en el directorio « path ».

QDir::Filters QFileSystemModel::filter() const

Devuelve el filtro especificado para el modelo de directorio.

Si no se ha establecido ningún filtro, el filtro predeterminado es QDir::AllEntries | QDir::NoDotAndDotDot | QDir::AllDirs.

Véase también setFilter() y QDir::Filters.

[override virtual] Qt::ItemFlags QFileSystemModel::flags(const QModelIndex &index) const

Reimplementa: ` QAbstractItemModel::flags(const QModelIndex &index) const`.

[override virtual] bool QFileSystemModel::hasChildren(const QModelIndex &parent = QModelIndex()) const

Reimplementa: ` QAbstractItemModel::hasChildren(const QModelIndex &parent) const`.

[override virtual] QVariant QFileSystemModel::headerData(int section, Qt::Orientation orientation, int role = Qt::DisplayRole) const

Reimplementa: ` QAbstractItemModel::headerData(int section, Qt::Orientation orientation, int role) const`.

QAbstractFileIconProvider *QFileSystemModel::iconProvider() const

Devuelve el proveedor de iconos de archivos para este modelo de directorio.

Véase también setIconProvider().

[override virtual] QModelIndex QFileSystemModel::index(int row, int column, const QModelIndex &parent = QModelIndex()) const

Reimplementa: ` QAbstractItemModel::index` (int fila, int columna, const QModelIndex &padre) const.

QModelIndex QFileSystemModel::index(const QString &path, int column = 0) const

Devuelve el índice del elemento del modelo correspondiente a los valores indicados en « path » y « column ».

Esta es una función sobrecargada.

bool QFileSystemModel::isDir(const QModelIndex &index) const

Devuelve « true » si el elemento del modelo « index » representa un directorio; en caso contrario, devuelve « false ».

QDateTime QFileSystemModel::lastModified(const QModelIndex &index) const

Devuelve la fecha y la hora (en hora local) en que se modificó por última vez index.

Se trata de una función sobrecargada, equivalente a llamar a:

lastModified(index, QTimeZone::LocalTime);

Si index no es válido, se devuelve un objeto QDateTime construido por defecto.

[since 6.6] QDateTime QFileSystemModel::lastModified(const QModelIndex &index, const QTimeZone &tz) const

Devuelve la fecha y la hora, en la zona horaria tz, en la que se modificó por última vez index.

Los argumentos habituales para tz son QTimeZone::UTC o QTimeZone::LocalTime. El UTC no requiere ninguna conversión a partir de la hora devuelta por la API nativa del sistema de archivos, por lo que obtener la hora en UTC es potencialmente más rápido. Normalmente se elige LocalTime si la hora se muestra al usuario.

Si index no es válido, se devuelve un QDateTime construido por defecto.

Esta función se introdujo en Qt 6.6.

[override virtual] QMimeData *QFileSystemModel::mimeData(const QModelIndexList &indexes) const

Reimplementa: ` QAbstractItemModel::mimeData(const QModelIndexList &indexes) const`.

Devuelve un objeto que contiene una descripción serializada de la lista de índices especificada ` indexes`. El formato utilizado para describir los elementos correspondientes a los índices se obtiene de la función ` mimeTypes()`.

Si la lista de índices está vacía, se devuelve nullptr en lugar de una lista vacía serializada.

[override virtual] QStringList QFileSystemModel::mimeTypes() const

Reimplementa: ` QAbstractItemModel::mimeTypes()` const.

Devuelve una lista de tipos MIME que se pueden utilizar para describir una lista de elementos del modelo.

QModelIndex QFileSystemModel::mkdir(const QModelIndex &parent, const QString &name)

Crea un directorio con el nombre « name » en el índice del modelo « parent ».

QVariant QFileSystemModel::myComputer(int role = Qt::DisplayRole) const

Devuelve los datos almacenados en la ruta role para el elemento «Mi PC».

Véase también Qt::ItemDataRole.

QStringList QFileSystemModel::nameFilters() const

Devuelve una lista de los filtros aplicados a los nombres del modelo.

Véase también setNameFilters().

[override virtual] QModelIndex QFileSystemModel::parent(const QModelIndex &index) const

Reimplementa: ` QAbstractItemModel::parent(const QModelIndex &index) const`.

QFileDevice::Permissions QFileSystemModel::permissions(const QModelIndex &index) const

Devuelve la combinación completa, unida mediante la operación «OR», de QFile::Permission para el ` index`.

bool QFileSystemModel::remove(const QModelIndex &index)

Elimina el elemento del modelo « index » del modelo del sistema de archivos y borra el archivo correspondiente del sistema de archivos, devolviendo «true» si la operación se realiza con éxito. Si no se puede eliminar el elemento, se devuelve «false».

Advertencia: Esta función elimina archivos del sistema de archivos; no los traslada a una ubicación desde la que puedan recuperarse.

Véase también rmdir().

bool QFileSystemModel::rmdir(const QModelIndex &index)

Elimina el directorio correspondiente al elemento del modelo « index » en el sistema de archivos del modelo y borra el directorio correspondiente del sistema de archivos, devolviendo «true» si la operación se realiza con éxito. Si no se puede eliminar el directorio, se devuelve «false».

Advertencia: Esta función elimina directorios del sistema de archivos; no los mueve a una ubicación desde la que puedan recuperarse.

Véase también remove().

[override virtual] QHash<int, QByteArray> QFileSystemModel::roleNames() const

Reimplementa: ` QAbstractItemModel::roleNames()` const.

QDir QFileSystemModel::rootDirectory() const

El directorio establecido actualmente

Véase también rootPath().

QString QFileSystemModel::rootPath() const

La ruta raíz establecida actualmente

Véase también setRootPath() y rootDirectory().

[signal] void QFileSystemModel::rootPathChanged(const QString &newPath)

Esta señal se emite cada vez que la ruta raíz se ha cambiado a newPath.

[override virtual] int QFileSystemModel::rowCount(const QModelIndex &parent = QModelIndex()) const

Reimplementa: QAbstractItemModel::rowCount(const QModelIndex &parent) const.

[override virtual] bool QFileSystemModel::setData(const QModelIndex &idx, const QVariant &value, int role = Qt::EditRole)

Reimplementa: QAbstractItemModel::setData(const QModelIndex &index, const QVariant &value, int role).

Véase también data().

void QFileSystemModel::setFilter(QDir::Filters filters)

Establece el filtro del modelo de directorio en el especificado por filters.

Ten en cuenta que el filtro que establezcas debe incluir siempre el valor de la enumeración QDir::AllDirs; de lo contrario, QFileSystemModel no podrá leer la estructura del directorio.

Véase también filter() y QDir::Filters.

void QFileSystemModel::setIconProvider(QAbstractFileIconProvider *provider)

Establece la propiedad « provider » de los iconos de los archivos para el modelo de directorio.

Véase también iconProvider().

void QFileSystemModel::setNameFilters(const QStringList &filters)

Establece el nombre « filters » para aplicarlo a los archivos existentes.

Véase también nameFilters().

void QFileSystemModel::setOption(QFileSystemModel::Option option, bool on = true)

Establece la propiedad « option » para que esté habilitada si « on » es «true»; en caso contrario, deshabilita la propiedad « option ».

Las opciones deben configurarse antes de modificar las propiedades.

Véase también options y testOption().

QModelIndex QFileSystemModel::setRootPath(const QString &newPath)

Establece el directorio que supervisa el modelo en « newPath » mediante la instalación de un « file system watcher » en él. Cualquier cambio en los archivos y directorios de este directorio se reflejará en el modelo.

Si se modifica la ruta, se emitirá la señal rootPathChanged().

Nota: Esta función no cambia la estructura del modelo ni modifica los datos disponibles para las vistas. En otras palabras, la «raíz» del modelo no se modifica para incluir únicamente los archivos y directorios que se encuentran dentro del directorio especificado por newPath en el sistema de archivos.

Véase también rootPath(), QTreeView::setRootIndex() y TreeView::rootIndex.

[override virtual] QModelIndex QFileSystemModel::sibling(int row, int column, const QModelIndex &idx) const

Reimplementa: ` QAbstractItemModel::sibling` (int row, int column, const QModelIndex &index) const.

qint64 QFileSystemModel::size(const QModelIndex &index) const

Devuelve el tamaño, en bytes, de index. Si el archivo no existe, se devuelve 0.

[override virtual] void QFileSystemModel::sort(int column, Qt::SortOrder order = Qt::AscendingOrder)

Reimplementa: ` QAbstractItemModel::sort` (int column, Qt::SortOrder order).

[override virtual] Qt::DropActions QFileSystemModel::supportedDropActions() const

Reimplementa: ` QAbstractItemModel::supportedDropActions()` const.

bool QFileSystemModel::testOption(QFileSystemModel::Option option) const

Devuelve ` true ` si el ` option ` indicado está habilitado; en caso contrario, devuelve `false`.

Véase también options y setOption().

[override virtual protected] void QFileSystemModel::timerEvent(QTimerEvent *event)

Reimplementa: ` QObject::timerEvent(QTimerEvent *event)`.

QString QFileSystemModel::type(const QModelIndex &index) const

Devuelve el tipo de archivo index, como «Directorio» o «Archivo JPEG».

© 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.