En esta página

QFileSystemModel Class

La clase QFileSystemModel provee un modelo de datos para el sistema de archivos local. Más...

Cabecera: #include <QFileSystemModel>
CMake: find_package(Qt6 REQUIRED COMPONENTS Gui)
target_link_libraries(mytarget PRIVATE Qt6::Gui)
qmake: QT += gui
Hereda: 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 proporciona acceso al sistema de ficheros local, proporcionando funciones para renombrar y eliminar ficheros y directorios, y para crear nuevos directorios. En el caso más simple, puede ser utilizado con un widget de visualización adecuado como parte de un navegador o filtro.

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

Ejemplo de uso

Un modelo de directorio que muestra el contenido de un directorio por defecto se construye normalmente con un objeto padre:

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

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

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

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

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

El índice raíz de la vista se puede utilizar para controlar cuánto de un modelo jerárquico se muestra. QFileSystemModel proporciona una función conveniente 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 separado para poblarse a si mismo, por lo que no causará que el hilo principal se cuelgue mientras se consulta el sistema de ficheros. Las llamadas a rowCount() devolverán 0 hasta que el modelo rellene un directorio. El hilo en el que vive QFileSystemModel necesita ejecutar un bucle de eventos para procesar los datos entrantes.

QFileSystemModel no comenzará a poblarse hasta que setRootPath() sea llamado. Esto previene cualquier consulta innecesaria del sistema de archivos raiz del sistema, como enumerar las unidades en Windows, hasta ese momento.

QFileSystemModel mantiene una caché con información de ficheros. La caché se mantiene actualizada automáticamente utilizando la función QFileSystemWatcher.

Ver también Clases Modelo.

Documentación de Tipos de Miembros

enum QFileSystemModel::Opción
flags QFileSystemModel::Opciones

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

El tipo Options es un typedef para QFlags<Option>. Almacena una combinación OR de valores 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 la propiedad

nameFilterDisables : bool

Esta propiedad indica si los archivos que no pasan el filtro de nombre están ocultos o deshabilitados

Esta propiedad es true por defecto

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 cambiar 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 directorio permite escribir en el sistema de ficheros.

Si esta propiedad es falsa, el modelo de directorio permitirá renombrar, copiar y borrar ficheros y directorios.

Esta propiedad es true por defecto

Funciones de acceso:

bool isReadOnly() const
void setReadOnly(bool enable)

Esta propiedad indica si el modelo de directorio debe resolver enlaces simbólicos.

Sólo es relevante en Windows.

Por defecto, esta propiedad es true.

Funciones de acceso:

bool resolveSymlinks() const
void setResolveSymlinks(bool enable)

Véase también QFileSystemModel::Options.

Documentación de las funciones miembro

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

Construye un modelo de sistema de archivos con la dirección parent.

[virtual noexcept] QFileSystemModel::~QFileSystemModel()

Destruye 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 rol) const.

Véase también setData().

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

Esta señal se emite cuando el hilo recolector ha terminado de cargar la página 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).

Maneja el data suministrado por una operación de arrastrar y soltar que terminó con el action dado sobre la fila en el modelo especificado por los row y column y 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 la dirección index.

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

Devuelve el QFileInfo para el artículo almacenado en el modelo bajo el index dado.

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

Devuelve el nombre de archivo del elemento almacenado en el modelo bajo la dirección index.

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

Devuelve la ruta del elemento almacenado en el modelo bajo el index dado.

[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 oldName se renombra con éxito 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 un filtro, el filtro por defecto 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 archivo 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 &parent) const.

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

Devuelve el índice del elemento del modelo para path y column.

Se trata de 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 hora (en hora local) en que index se modificó por última vez.

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

lastModified(index, QTimeZone::LocalTime);

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

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

Devuelve la fecha y hora, en la zona horaria tz, en que index fue modificado por última vez.

Los argumentos típicos para tz son QTimeZone::UTC o QTimeZone::LocalTime. UTC no requiere ninguna conversión 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 se muestra la hora 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 del indexes especificado. 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 pueden utilizarse para describir una lista de elementos del modelo.

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

Cree un directorio con la dirección name en el índice del modelo parent.

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

Devuelve los datos almacenados en la dirección role dada para el elemento "Mi PC".

Véase también Qt::ItemDataRole.

QStringList QFileSystemModel::nameFilters() const

Devuelve una lista de 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 OR-ed together 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 elimina el archivo correspondiente del sistema de archivos, devolviendo true si se ha realizado correctamente. Si no se puede eliminar el elemento, se devuelve false.

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

Véase también rmdir().

bool QFileSystemModel::rmdir(const QModelIndex &index)

Elimina el directorio correspondiente al elemento del modelo index en el modelo del sistema de archivos y elimina el directorio correspondiente del sistema de archivos, devolviendo true si se ha realizado correctamente. Si el directorio no puede ser eliminado, devuelve false.

Advertencia: Esta función borra directorios del sistema de ficheros; no los mueve a una ubicación donde puedan ser recuperados.

Véase también remove().

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

Reimplementa: QAbstractItemModel::roleNames() const.

QDir QFileSystemModel::rootDirectory() const

El directorio configurado 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 siempre que la ruta raíz se ha cambiado a una 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 al especificado por filters.

Ten en cuenta que el filtro que establezcas debe incluir siempre el valor enum 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 el provider de los iconos de archivo para el modelo de directorio.

Véase también iconProvider().

void QFileSystemModel::setNameFilters(const QStringList &filters)

Establece el nombre filters que se aplicará a los archivos existentes.

Véase también nameFilters().

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

Establece el option dado para ser habilitado si on es verdadero; de lo contrario, borra el option dado.

Las opciones deben establecerse antes de cambiar las propiedades.

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

QModelIndex QFileSystemModel::setRootPath(const QString &newPath)

Establece el directorio que está siendo vigilado por el modelo en newPath instalando un file system watcher en él. Cualquier cambio en los archivos y directorios dentro de este directorio se reflejará en el modelo.

Si se cambia 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 archivos y directorios 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 fila, int columna, 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 columna, Qt::SortOrder orden).

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

Reimplementa: QAbstractItemModel::supportedDropActions() const.

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

Devuelve true si el option dado 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.