이 페이지에서

QFileSystemModel Class

QFileSystemModel 클래스는 로컬 파일 시스템에 대한 데이터 모델을 제공합니다. 더 보기...

헤더: #include <QFileSystemModel>
CMake: find_package(Qt6 REQUIRED COMPONENTS Gui)
target_link_libraries(mytarget PRIVATE Qt6::Gui)
qmake: QT += gui
상속: QAbstractItemModel

공개 유형

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

속성

공개 함수

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

재구현된 공용 함수

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

신호

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

재구현된 보호 함수

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

상세 설명

이 클래스는 로컬 파일 시스템에 대한 액세스를 제공하며, 파일 및 디렉터리의 이름 변경, 삭제, 그리고 새 디렉터리 생성을 위한 함수를 제공합니다. 가장 간단한 경우, 브라우저나 필터의 일부로 적절한 표시 위젯과 함께 사용할 수 있습니다.

QFileSystemModel은 ` QAbstractItemModel`가 제공하는 표준 인터페이스를 통해 접근할 수 있지만, 디렉터리 모델에 특화된 몇 가지 편의 함수도 제공합니다. ` fileInfo()`, ` isDir()`, ` fileName()` 및 ` filePath()` 함수는 모델 내 항목과 관련된 기본 파일 및 디렉터리에 대한 정보를 제공합니다. 디렉터리는 ` mkdir()` 및 ` rmdir()`를 사용하여 생성하거나 삭제할 수 있습니다.

사용 예

기본 디렉터리의 내용을 표시하는 디렉터리 모델은 일반적으로 부모 객체를 사용하여 구성됩니다:

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

트리 뷰를 사용하여 모델의 내용을 표시할 수 있으며

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

특정 디렉터리의 내용은 트리 뷰의 루트 인덱스를 설정하여 표시할 수 있습니다:

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

뷰의 루트 인덱스를 사용하면 계층적 모델 중 어느 정도를 표시할지 제어할 수 있습니다. QFileSystemModel은 모델 내 디렉터리 경로에 적합한 모델 인덱스를 반환하는 편리한 함수를 제공합니다.

캐싱 및 성능

QFileSystemModel은 자체 데이터를 채우기 위해 별도의 스레드를 사용하므로, 파일 시스템을 조회하는 동안 메인 스레드가 멈추는 현상을 일으키지 않습니다. rowCount() 호출은 모델이 디렉터리를 채울 때까지 ` 0 `를 반환합니다. QFileSystemModel이 실행되는 스레드에서는 들어오는 데이터를 처리하기 위해 이벤트 루프를 실행해야 합니다.

QFileSystemModel은 setRootPath()이 호출될 때까지 자체 데이터를 채우기 시작하지 않습니다. 이를 통해 해당 시점까지는 Windows에서 드라이브 열거와 같은 시스템의 루트 파일 시스템에 대한 불필요한 쿼리가 방지됩니다.

QFileSystemModel은 파일 정보가 담긴 캐시를 유지합니다. 이 캐시는 ` QFileSystemWatcher`를 사용하여 자동으로 최신 상태로 유지됩니다.

‘모델 클래스’항목도 참조하십시오 .

멤버 유형 설명서

enum QFileSystemModel::Option
flags QFileSystemModel::Options

상수값설명
QFileSystemModel::DontWatchForChanges0x00000001경로에 파일 감시자를 추가하지 않습니다. 이렇게 하면 줄 편집 완성 같은 간단한 작업에 모델을 사용할 때 오버헤드를 줄일 수 있습니다.
QFileSystemModel::DontResolveSymlinks0x00000002파일 시스템 모델에서 심볼릭 링크를 해결하지 않습니다. 기본적으로 심볼릭 링크는 해결됩니다.
QFileSystemModel::DontUseCustomDirectoryIcons0x00000004항상 기본 디렉터리 아이콘을 사용합니다. 일부 플랫폼에서는 사용자가 다른 아이콘을 설정할 수 있습니다. 사용자 정의 아이콘 조회는 네트워크 또는 이동식 드라이브에서 성능에 큰 영향을 미칩니다. 이 설정은 아이콘 공급자에서 QFileIconProvider::DontUseCustomDirectoryIcons 옵션을 그에 따라 설정합니다.

Options 유형은 QFlags<Option>에 대한 typedef입니다. 이 유형은 Option 값들의 OR 조합을 저장합니다.

resolveSymlinks도 참조하십시오 .

enum QFileSystemModel::Roles

상수값설명
QFileSystemModel::FileIconRoleQt::DecorationRole 
QFileSystemModel::FilePathRoleQt::UserRole + 1 
QFileSystemModel::FileNameRoleQt::UserRole + 2 
QFileSystemModel::FilePermissionsQt::UserRole + 3 
QFileSystemModel::FileInfoRoleQt::FileInfoRole인덱스에 대한 ` QFileInfo ` 객체

속성 설명

nameFilterDisables : bool

이 속성은 이름 필터를 통과하지 못한 파일이 숨겨지거나 비활성화되는지 여부를 결정합니다.

이 속성의 기본값은 ` true `입니다

액세스 함수:

bool nameFilterDisables() const
void setNameFilterDisables(bool enable)

options : Options

이 속성은 모델에 영향을 미치는 다양한 옵션을 포함합니다.

기본적으로 모든 옵션은 비활성화되어 있습니다.

속성을 변경하기 전에 옵션을 설정해야 합니다.

액세스 함수:

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

setOption() 및 testOption()도 참조하십시오 .

readOnly : bool

이 속성은 디렉터리 모델이 파일 시스템에 대한 쓰기 작업을 허용하는지 여부를 나타냅니다.

이 속성이 false로 설정된 경우, 디렉터리 모델은 파일 및 디렉터리의 이름 변경, 복사 및 삭제를 허용합니다.

이 속성의 기본값은 ` true `입니다

액세스 함수:

bool isReadOnly() const
void setReadOnly(bool enable)

이 속성은 디렉터리 모델이 심볼릭 링크를 해결해야 하는지 여부를 결정합니다.

이는 Windows에서만 적용됩니다.

기본적으로 이 속성의 값은 ` true`입니다.

액세스 함수:

bool resolveSymlinks() const
void setResolveSymlinks(bool enable)

QFileSystemModel::Options도 참조하십시오 .

멤버 함수 설명서

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

지정된 ` parent`을 사용하여 파일 시스템 모델을 생성합니다.

[virtual noexcept] QFileSystemModel::~QFileSystemModel()

이 파일 시스템 모델을 삭제합니다.

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

QAbstractItemModel::canFetchMore(const QModelIndex &parent) const를 재구현합니다.

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

QAbstractItemModel::columnCount(const QModelIndex &parent) const를 재구현합니다.

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

QAbstractItemModel::data(const QModelIndex &index, int role) const를 재구현합니다.

setData()도 참조하십시오 .

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

이 신호는 수집자 스레드가 ` path`의 로딩을 완료했을 때 발생합니다.

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

QAbstractItemModel::dropMimeData(const QMimeData *data, Qt::DropAction action, int row, int column, const QModelIndex &parent)를 재구현합니다.

row 및 column 로 지정된 모델의 행에서 parent 인덱스를 통해 주어진 드래그 앤 드롭( action )으로 종료된 드래그 앤 드롭 작업에서 제공된 data 를 처리합니다. 작업이 성공하면 true를 반환합니다.

supportedDropActions()도 참조하십시오 .

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

QObject::event(QEvent *e)를 재구현합니다.

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

QAbstractItemModel::fetchMore(const QModelIndex &parent)를 재구현합니다.

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

지정된 ` index` 아래 모델에 저장된 항목의 아이콘을 반환합니다.

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

지정된 ` index` 아래 모델에 저장된 항목에 대한 ` QFileInfo `를 반환합니다.

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

지정된 ` index` 아래 모델에 저장된 항목의 파일 이름을 반환합니다.

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

지정된 ` index ` 아래 모델에 저장된 항목의 경로를 반환합니다.

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

이 신호는 oldName 이라는 이름의 파일이 newName 로 성공적으로 이름이 변경될 때마다 발생합니다. 해당 파일은 path 디렉터리에 위치해 있습니다.

QDir::Filters QFileSystemModel::filter() const

디렉터리 모델에 지정된 필터를 반환합니다.

필터가 설정되지 않은 경우, 기본 필터는 QDir::AllEntries | QDir::NoDotAndDotDot | QDir::AllDirs 입니다.

setFilter() 및 QDir::Filters도 참조하십시오 .

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

QAbstractItemModel::flags(const QModelIndex &index) const를 재구현합니다.

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

QAbstractItemModel::hasChildren(const QModelIndex &parent) const를 재구현합니다.

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

QAbstractItemModel::headerData(int section, Qt::Orientation orientation, int role) const를 재구현합니다.

QAbstractFileIconProvider *QFileSystemModel::iconProvider() const

이 디렉터리 모델에 대한 파일 아이콘 제공자를 반환합니다.

setIconProvider()도 참조하십시오 .

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

QAbstractItemModel::index(int row, int column, const QModelIndex &parent) const를 재구현합니다.

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

주어진 ` path ` 및 ` column`에 대한 모델 항목 인덱스를 반환합니다.

이 함수는 오버로드된 함수입니다.

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

모델 항목 index 이 디렉터리를 나타내는 경우 true 을 반환하고, 그렇지 않은 경우 false 을 반환합니다.

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

index 가 마지막으로 수정된 날짜와 시간(현지 시간 기준)을 반환합니다.

이 함수는 오버로딩된 함수이며, 다음 호출과 동일합니다:

lastModified(index, QTimeZone::LocalTime);

index 가 유효하지 않은 경우, 기본 생성된 QDateTime 가 반환됩니다.

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

tz 시간대에서 index 이 마지막으로 수정된 날짜와 시간을 반환합니다.

tz 의 일반적인 인수는 QTimeZone::UTC 또는 QTimeZone::LocalTime 입니다. UTC의 경우 네이티브 파일 시스템 API에서 반환된 시간을 별도로 변환할 필요가 없으므로, UTC로 시간을 가져오는 것이 잠재적으로 더 빠를 수 있습니다. 사용자에게 시간을 표시해야 하는 경우에는 일반적으로 LocalTime이 선택됩니다.

index 가 유효하지 않은 경우, 기본 생성된 QDateTime 가 반환됩니다.

이 함수는 Qt 6.6에서 도입되었습니다.

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

QAbstractItemModel::mimeData(const QModelIndexList &indexes) const를 재구현합니다.

지정된 ` indexes`의 직렬화된 설명을 포함하는 객체를 반환합니다. 인덱스에 해당하는 항목을 설명하는 데 사용되는 형식은 ` mimeTypes()` 함수에서 가져옵니다.

인덱스 목록이 비어 있는 경우, 직렬화된 빈 목록 대신 nullptr 가 반환됩니다.

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

QAbstractItemModel::mimeTypes() const를 재구현합니다.

모델 내 항목 목록을 설명하는 데 사용할 수 있는 MIME 유형 목록을 반환합니다.

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

parent 모델 인덱스 내에 ‘ name ’라는 디렉터리를 생성합니다.

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

지정된 role 에 저장된 “내 컴퓨터” 항목에 대한 데이터를 반환합니다.

Qt::ItemDataRole도 참조하십시오 .

QStringList QFileSystemModel::nameFilters() const

모델 내 이름에 적용된 필터 목록을 반환합니다.

setNameFilters()도 참조하십시오 .

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

QAbstractItemModel::parent(const QModelIndex &index) const를 재구현합니다.

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

index 에 대한 QFile::Permission의 모든 값을 OR 연산으로 결합한 결과를 반환합니다.

bool QFileSystemModel::remove(const QModelIndex &index)

파일 시스템 모델에서 모델 항목 index 을 제거하고 파일 시스템에서 해당 파일을 삭제하며, 성공하면 true를 반환합니다. 항목을 제거할 수 없는 경우 false를 반환합니다.

경고: 이 함수는 파일 시스템에서 파일을 삭제하며, 복구 가능한 위치로 파일을 이동시키지 않습니다.

참조: rmdir()

bool QFileSystemModel::rmdir(const QModelIndex &index)

파일 시스템 모델 내의 모델 항목 index 에 해당하는 디렉터리를 제거하고, 파일 시스템에서 해당 디렉터리를 삭제하며, 성공 시 true를 반환합니다. 디렉터리를 제거할 수 없는 경우 false를 반환합니다.

경고: 이 함수는 파일 시스템에서 디렉터리를 삭제하며, 복구 가능한 위치로 이동시키지는 않습니다.

참조: remove().

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

QAbstractItemModel::roleNames() const를 재구현합니다.

QDir QFileSystemModel::rootDirectory() const

현재 설정된 디렉터리

rootPath()도 참조하십시오 .

QString QFileSystemModel::rootPath() const

현재 설정된 루트 경로

setRootPath() 및 rootDirectory()도 참조하십시오 .

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

루트 경로가 newPath 으로 변경될 때마다 이 신호가 전송됩니다.

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

QAbstractItemModel::rowCount(const QModelIndex &parent) const를 재구현합니다.

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

QAbstractItemModel::setData(const QModelIndex &index, const QVariant &value, int role)를 재구현합니다.

data()도 참조하십시오 .

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

디렉터리 모델의 필터를 filters 에 지정된 값으로 설정합니다.

설정한 필터에는 항상 QDir::AllDirs 열거형 값이 포함되어야 합니다. 그렇지 않으면 QFileSystemModel 가 디렉터리 구조를 읽을 수 없습니다.

filter() 및 QDir::Filters도 참조하십시오 .

void QFileSystemModel::setIconProvider(QAbstractFileIconProvider *provider)

디렉터리 모델의 파일 아이콘에 대한 ‘ provider ’를 설정합니다.

iconProvider()도 참조하십시오 .

void QFileSystemModel::setNameFilters(const QStringList &filters)

기존 파일에 적용할 이름 ‘ filters ’을 설정합니다.

nameFilters()도 참조하십시오 .

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

on 가 true인 경우, 지정된 option 를 활성화하고, 그렇지 않은 경우 지정된 option 를 해제합니다.

속성을 변경하기 전에 옵션을 설정해야 합니다.

options 및 testOption()도 참조하십시오 .

QModelIndex QFileSystemModel::setRootPath(const QString &newPath)

해당 디렉터리에 file system watcher 를 설치하여, 모델이 모니터링하는 디렉터리를 newPath 로 설정합니다. 이 디렉터리 내의 파일 및 디렉터리에 대한 모든 변경 사항은 모델에 반영됩니다.

경로가 변경되면 rootPathChanged() 신호가 발생합니다.

참고: 이 함수는 모델의 구조를 변경하거나 뷰에서 사용할 수 있는 데이터를 수정하지 않습니다. 즉, 모델의 “루트”가 파일 시스템에서 newPath 로 지정된 디렉터리 내의 파일과 디렉터리만 포함하도록 변경되지는 않습니다.

rootPath(), QTreeView::setRootIndex() 및 TreeView::rootIndex도 참조하십시오 .

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

QAbstractItemModel::sibling(int row, int column, const QModelIndex &index) const를 재구현합니다.

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

index 의 크기를 바이트 단위로 반환합니다. 파일이 존재하지 않으면 0을 반환합니다.

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

QAbstractItemModel::sort(int column, Qt::SortOrder order)를 재구현합니다.

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

QAbstractItemModel::supportedDropActions() const를 재구현합니다.

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

지정된 option 가 활성화되어 있으면 true 를 반환하고, 그렇지 않으면 false를 반환합니다.

options 및 setOption()도 참조하십시오 .

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

QObject::timerEvent(QTimerEvent *event)를 재구현합니다.

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

index 의 파일 유형(예: “디렉터리” 또는 “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.