QFile 类提供用于读写文件的接口。 更多...
| 头： | #include <QFile> |
| CMake: |
find_package(Qt6 REQUIRED COMPONENTS Core)
target_link_libraries(mytarget PRIVATE Qt6::Core) |
| qmake: | QT += core |
| 继承： | QFileDevice |
| 继承者： |
注意： 此类的所有函数 可重入 .
| QFile () | |
| QFile (const QString & name ) | |
(从 6.0 起)
|
QFile (const std::filesystem::path & name ) |
| QFile (QObject * parent ) | |
| QFile (const QString & name , QObject * parent ) | |
(从 6.0 起)
|
QFile (const std::filesystem::path & name , QObject * parent ) |
| virtual | ~QFile () |
| bool | copy (const QString & newName ) |
(从 6.0 起)
bool
|
copy (const std::filesystem::path & newName ) |
| bool | exists () const |
(从 6.0 起)
std::filesystem::path
|
filesystemFileName () const |
(since 6.3)
std::filesystem::path
|
filesystemSymLinkTarget () const |
| bool | link (const QString & linkName ) |
(从 6.0 起)
bool
|
link (const std::filesystem::path & newName ) |
| bool | moveToTrash () |
(since 6.3)
bool
|
open (QIODeviceBase::OpenMode mode , QFileDevice::Permissions permissions ) |
| bool | open (FILE * fh , QIODeviceBase::OpenMode mode , QFileDevice::FileHandleFlags handleFlags = DontCloseHandle) |
| bool | open (int fd , QIODeviceBase::OpenMode mode , QFileDevice::FileHandleFlags handleFlags = DontCloseHandle) |
| bool | remove () |
| bool | rename (const QString & newName ) |
(从 6.0 起)
bool
|
rename (const std::filesystem::path & newName ) |
| void | setFileName (const QString & name ) |
(从 6.0 起)
void
|
setFileName (const std::filesystem::path & name ) |
| QString | symLinkTarget () const |
| virtual QString | fileName () const override |
| virtual bool | open (QIODeviceBase::OpenMode mode ) override |
| virtual QFileDevice::Permissions | permissions () const override |
| virtual bool | resize (qint64 sz ) override |
| virtual bool | setPermissions (QFileDevice::Permissions permissions ) override |
| virtual qint64 | size () const override |
| bool | copy (const QString & fileName , const QString & newName ) |
| QString | decodeName (const QByteArray & localFileName ) |
| QString | decodeName (const char * localFileName ) |
| QByteArray | encodeName (const QString & fileName ) |
| bool | exists (const QString & fileName ) |
(since 6.3)
std::filesystem::path
|
filesystemSymLinkTarget (const std::filesystem::path & fileName ) |
| bool | link (const QString & fileName , const QString & linkName ) |
| bool | moveToTrash (const QString & fileName , QString * pathInTrash = nullptr) |
| QFileDevice::Permissions | permissions (const QString & fileName ) |
(从 6.0 起)
QFileDevice::Permissions
|
permissions (const std::filesystem::path & filename ) |
| bool | remove (const QString & fileName ) |
| bool | rename (const QString & oldName , const QString & newName ) |
| bool | resize (const QString & fileName , qint64 sz ) |
| bool | setPermissions (const QString & fileName , QFileDevice::Permissions permissions ) |
(从 6.0 起)
bool
|
setPermissions (const std::filesystem::path & filename , QFileDevice::Permissions permissionSpec ) |
| QString | symLinkTarget (const QString & fileName ) |
QFile 是 I/O 设备用于读写文本、二进制文件及 resources 。QFile 可以单独使用，或更方便一起使用与 QTextStream or QDataStream .
通常在构造函数中传递文件名，但可以随时设置它使用 setFileName ()。QFile 期望文件分隔符为 / 不管操作系统。不支持使用其它分隔符 (如：\)。
可以检查文件是否存在使用 exists ()，和移除文件使用 remove ()。(更高级的文件系统相关操作的提供由 QFileInfo and QDir )。
打开文件采用 open ()，关闭采用 close ()，和刷新采用 flush ()。数据的读写通常是使用 QDataStream or QTextStream ，但也可以调用 QIODevice 继承函数 read (), readLine (), readAll (), write ()。QFile 还继承 getChar (), putChar ()，和 ungetChar ()，每次操控一字符。
文件大小的返回是通过
size
()。可以获取当前文件位置使用
pos
()，或移至新文件位置使用
seek
()。若已到达 EOF (文件末尾)，
atEnd
() 返回
true
.
以下范例逐行读取文本文件：
QFile file("in.txt");
if (!file.open(QIODevice::ReadOnly | QIODevice::Text))
return;
while (!file.atEnd()) {
QByteArray line = file.readLine();
process_line(line);
}
把 QIODevice::Text 标志传递给 open () 告诉 Qt 要转换 Windows 样式行终止符 \r\n 成 C++ 样式终止符 \n。默认情况下，QFile 假定为二进制 (即：对存储在文件中的字节，不履行任何转换)。
下一范例使用 QTextStream 以逐行读取文本文件：
QFile file("in.txt");
if (!file.open(QIODevice::ReadOnly | QIODevice::Text))
return;
QTextStream in(&file);
while (!in.atEnd()) {
QString line = in.readLine();
process_line(line);
}
QTextStream 负责将存储在磁盘中的 8 位数据转换成 16 位 Unicode QString 。默认情况下，假定文件以 UTF-8 编码。这可以改变使用 QTextStream::setEncoding ().
要写入文本，可以使用操作符 <<()，重载以接受 QTextStream 在左侧和各种数据类型 (包括 QString ) 在右侧：
QFile file("out.txt");
if (!file.open(QIODevice::WriteOnly | QIODevice::Text))
return;
QTextStream out(&file);
out << "The magic number is: " << 49 << "\n";
QDataStream 类似，可以使用操作符 <<() 写入数据，和使用操作符 >>() 读回它。见类文档编制，了解细节。
不像其它 QIODevice 实现，譬如 QTcpSocket ，QFile 不会发射 aboutToClose (), bytesWritten ()，或 readyRead () 信号。此实现细节意味着 QFile 不适合读写某些类型的文件，譬如 Unix 平台中的设备文件。
I/O 相关 Qt API
使用 UTF-16 基 QString 来表示文件路径。标准 C++ API (
<cstdio>
or
<iostream>
) 或特定平台 API，不管怎样，经常需要 8 位编码的路径。可以使用
encodeName
() 和
decodeName
() 以在 2 种表示之间转换。
在 Unix，有一些特殊系统文件 (如在
/proc
) 其中
size
() 将始终返回 0，仍然可以从这种文件读取更多数据；直接生成数据是为响应调用
read
()。在此情况下，不管怎样，不可以使用
atEnd
() 以确定是否有更多数据要读取 (由于
atEnd
() 将返回 true 对于声明拥有大小 0 的文件)。相反，应该调用
readAll
()，或调用
read
() 或
readLine
() 重复，直到无法读取更多数据。下一范例使用
QTextStream
以读取
/proc/modules
逐行：
QFile file("/proc/modules");
if (!file.open(QIODevice::ReadOnly | QIODevice::Text))
return;
QTextStream in(&file);
QString line = in.readLine();
while (!line.isNull()) {
process_line(line);
line = in.readLine();
}
文件权限的处理是不同的，在像 Unix 系统和 Windows。在非 writable 目录像 Unix 系统，无法创建文件。在 Windows 并不始终如此，例如，"我的文档" 目录通常不可写，但可以在其中创建文件仍然是可能的。
Qt 对文件权限的理解是有限的，这尤其影响 QFile::setPermissions () 函数。在 Windows，Qt 将只设置遗留只读标志，且仅当未传递 Write* 标志时。Qt 不操纵 ACL (访问控制列表)，这使得此函数对 NTFS 卷几乎无用。它仍然可以用于使用 VFAT 文件系统的 U 盘。也不操纵 POSIX ACL。
在 Android，会应用一些局限性当处理 内容 URI (统一资源标识符) :
另请参阅 QTextStream , QDataStream , QFileInfo , QDir ，和 Qt 资源系统 .
构造 QFile 对象。
构造新文件对象以表示文件采用给定 name .
注意：
包括 Qt 6.8 及以上版本，为向后兼容，此构造函数是隐式的。从 Qt 6.9 开始，此构造函数是无条件
explicit
。用户可以强制此构造函数是
explicit
即使在早期 Qt 版本中，通过定义
QT_EXPLICIT_QFILE_CONSTRUCTION_FROM_PATH
宏在包括任何 Qt 头之前。
[since 6.0]
QFile::
QFile
(const
std::filesystem::path
&
name
)
构造新文件对象以表示文件采用给定 name .
注意：
包括 Qt 6.8 及以上版本，为向后兼容，此构造函数是隐式的。从 Qt 6.9 开始，此构造函数是无条件
explicit
。用户可以强制此构造函数是
explicit
即使在早期 Qt 版本中，通过定义
QT_EXPLICIT_QFILE_CONSTRUCTION_FROM_PATH
宏在包括任何 Qt 头之前。
该函数在 Qt 6.0 引入。
[explicit]
QFile::
QFile
(
QObject
*
parent
)
构造新文件对象采用给定 parent .
构造新文件对象采用给定 parent 表示文件采用指定 name .
[since 6.0]
QFile::
QFile
(const
std::filesystem::path
&
name
,
QObject
*
parent
)
构造新文件对象采用给定 parent 表示文件采用指定 name .
该函数在 Qt 6.0 引入。
[virtual noexcept]
QFile::
~QFile
()
销毁文件对象，关闭它若有必要。
拷贝文件命名 fileName () 到 newName .
此文件被关闭，在拷贝它之前。
若拷贝的文件是 symlink (符号链接)，拷贝的就是它引用的文件，而不是链接本身。除拷贝权限外，不会拷贝其它文件元数据。
返回
true
若成功；否则返回
false
.
注意：若文件采用名称
newName
已存在，copy() 返回
false
。这意味着
QFile
不会覆写它。
注意：
在 Android，此操作尚不支持
content
方案 URI (统一资源标识符)。
另请参阅 setFileName ().
[static]
bool
QFile::
copy
(const
QString
&
fileName
, const
QString
&
newName
)
这是重载函数。
拷贝文件命名 fileName to newName .
此文件被关闭，在拷贝它之前。
若拷贝的文件是 symlink (符号链接)，拷贝的就是它引用的文件，而不是链接本身。除拷贝权限外，不会拷贝其它文件元数据。
返回
true
若成功；否则返回
false
.
注意：若文件采用名称
newName
已存在，copy() 返回
false
。这意味着
QFile
不会覆写它。
注意：
在 Android，此操作尚不支持
content
方案 URI (统一资源标识符)。
另请参阅 rename ().
[since 6.0]
bool
QFile::
copy
(const
std::filesystem::path
&
newName
)
这是重载函数。
该函数在 Qt 6.0 引入。
[static]
QString
QFile::
decodeName
(const
QByteArray
&
localFileName
)
这做反向 QFile::encodeName () 使用 localFileName .
另请参阅 encodeName ().
[static]
QString
QFile::
decodeName
(const
char
*
localFileName
)
这是重载函数。
返回 Unicode 版本为给定 localFileName 。见 encodeName () 了解细节。
[static]
QByteArray
QFile::
encodeName
(const
QString
&
fileName
)
转换 fileName 成可以用于本机 API 的 8 位编码。在 Windows，编码是来自活动 Windows (ANSI) 代码页的编码。在其它平台，这对于 macOS 是分解形式 (NFD) 的 UTF-8。
另请参阅 decodeName ().
[static]
bool
QFile::
exists
(const
QString
&
fileName
)
返回
true
若文件指定通过
fileName
存在；否则返回
false
.
注意： 若 fileName 是指向不存在文件的符号链接，返回 false。
这是重载函数。
返回
true
若文件指定通过
fileName
() 存在；否则返回
false
.
另请参阅 fileName () 和 setFileName ().
[override virtual]
QString
QFile::
fileName
() const
重实现： QFileDevice::fileName() const .
返回名称设置通过 setFileName () 或到 QFile 构造函数。
另请参阅 setFileName () 和 QFileInfo::fileName ().
[since 6.0]
std::filesystem::path
QFile::
filesystemFileName
() const
返回
fileName
() 作为
std::filesystem::path
.
该函数在 Qt 6.0 引入。
[since 6.3]
std::filesystem::path
QFile::
filesystemSymLinkTarget
() const
返回
symLinkTarget
() 作为
std::filesystem::path
.
该函数在 Qt 6.3 引入。
[static, since 6.3]
std::filesystem::path
QFile::
filesystemSymLinkTarget
(const
std::filesystem::path
&
fileName
)
返回
symLinkTarget
() 作为
std::filesystem::path
of
fileName
.
该函数在 Qt 6.3 引入。
创建链接命名
linkName
指向文件目前指定通过
fileName
()。链接是什么从属底层文件系统 (不管是 Windows 快捷方式，还是 Unix 符号链接)。返回
true
若成功；否则返回
false
.
此函数不会覆写文件系统中已存在的实体；在此情况下，
link()
将返回 false 并设置
error
() 返回
RenameError
.
注意：
要在 Windows 创建有效链接，
linkName
必须拥有
.lnk
文件扩展名。
另请参阅 setFileName ().
[static]
bool
QFile::
link
(const
QString
&
fileName
, const
QString
&
linkName
)
这是重载函数。
创建链接命名
linkName
指向文件
fileName
。链接是什么从属底层文件系统 (不管是 Windows 快捷方式，还是 Unix 符号链接)。返回
true
若成功；否则返回
false
.
另请参阅 link ().
[since 6.0]
bool
QFile::
link
(const
std::filesystem::path
&
newName
)
这是重载函数。
该函数在 Qt 6.0 引入。
移动指定文件按
fileName
() 到垃圾桶。返回
true
若成功，并设置
fileName
() 为可以在垃圾桶中找到的文件路径；否则返回
false
.
此函数运行时，独立于要丢到垃圾桶的文件大小。若在目录调用此函数，可能与要丢到垃圾桶的文件数成正比。
此函数使用 Windows 和 macOS API，在这 2 操作系统履行丢到垃圾桶。在其它地方 (Unix 系统)，此函数实现 FreeDesktop.org 垃圾桶规范，第 1.0 版 .
注意：
当使用 FreeDesktop.org 垃圾桶实现时，此函数将失败，若无法通过重命名和硬链接文件方式把文件移到垃圾桶位置。此条件出现，若位于当前用户没有权限卷 (挂载点) 要丢到垃圾桶的文件将创建
.Trash
目录，或采用一些不寻常文件系统类型或配置 (譬如：自身不是挂载点的子卷)。
注意： 在系统 API 不报告垃圾桶中文件位置的系统中， fileName () 会被设为 null 字符串，一旦移动文件。在没有垃圾桶的系统中，此函数始终返回 false。
[static]
bool
QFile::
moveToTrash
(const
QString
&
fileName
,
QString
*
pathInTrash
= nullptr)
这是重载函数。
移动指定文件按
fileName
到垃圾桶。返回
true
若成功，并设置
pathInTrash
(若有提供) 为可以在垃圾桶中找到的文件路径；否则返回
false
.
此函数运行时，独立于要丢到垃圾桶的文件大小。若在目录调用此函数，可能与要丢到垃圾桶的文件数成正比。
此函数使用 Windows 和 macOS API，在这 2 操作系统履行丢到垃圾桶。在其它地方 (Unix 系统)，此函数实现 FreeDesktop.org 垃圾桶规范，第 1.0 版 .
注意：
当使用 FreeDesktop.org 垃圾桶实现时，此函数将失败，若无法通过重命名和硬链接文件方式把文件移到垃圾桶位置。此条件出现，若位于当前用户没有权限卷 (挂载点) 要丢到垃圾桶的文件将创建
.Trash
目录，或采用一些不寻常文件系统类型或配置 (譬如：自身不是挂载点的子卷)。
注意： 在系统 API 不报告垃圾桶中文件路径在哪里的系统中， pathInTrash 会被设为 null 字符串，一旦移动文件。在没有垃圾桶的系统中，此函数始终返回 false。
[override virtual]
bool
QFile::
open
(
QIODeviceBase::OpenMode
mode
)
重实现： QIODevice::open (QIODeviceBase::OpenMode mode).
打开文件使用 OpenMode mode ，返回 true，若成功；否则返回 false。
The mode 必须为 QIODevice::ReadOnly、QIODevice::WriteOnly、或 QIODevice::ReadWrite。它还可以拥有额外标志，譬如 QIODevice::Text 和 QIODevice::Unbuffered。
注意： 在 WriteOnly or ReadWrite 方式，若相关文件不存在，此函数将试着创建新文件，在打开它之前。在 POSIX 系统，将以 umask 掩码 0666 方式创建文件，并具有从 Windows 父级目录继承的权限。在 Android，期望有访问文件名父级的权限，否则，创建这个不存在的文件将不可能。
另请参阅 QIODevice::OpenMode and setFileName ().
[since 6.3]
bool
QFile::
open
(
QIODeviceBase::OpenMode
mode
,
QFileDevice::Permissions
permissions
)
这是重载函数。
若文件不存在且 mode 会隐含创建它，它的创建是采用指定 permissions .
在 POSIX 系统，实际权限的影响是通过值
umask
.
在 Windows，是使用 ACL (访问控制列表) 模拟权限。这些 ACL (访问控制列表) 可以是非规范次序，当授予组的权限比其它组少时。具有这种权限的文件和目录将生成警告，当打开 Properties 对话框的 Security 选项卡时。向组授予授予其它组的所有权限，能避免这种警告。
该函数在 Qt 6.3 引入。
另请参阅 QIODevice::OpenMode and setFileName ().
这是重载函数。
打开现有文件句柄
fh
以给定
mode
.
handleFlags
可以用于指定额外选项。返回
true
若成功；否则返回
false
.
范例：
#include <stdio.h> void printError(const char* msg) { QFile file; file.open(stderr, QIODevice::WriteOnly); file.write(msg, qstrlen(msg)); // write to stderr file.close(); }
当 QFile 是使用此函数打开的，行为对于 close () 的控制是通过 AutoCloseHandle 标志。若 AutoCloseHandle 有指定，且此函数成功，那么调用 close () 会关闭采纳句柄。否则， close () 不会实际关闭文件，而仅刷新它。
警告：
stdin
,
stdout
，或
stderr
，可能无法
seek
().
size
() 返回
0
在此情况下。见
QIODevice::isSequential
() 了解更多信息。
Windows 平台注意事项
fh 必须以二进制方式打开 (即：mode 字符串必须包含 b，如在 rb 或 wb) 当访问文件及其它随机访问设备时。Qt 将翻译行尾字符，若把 QIODevice::Text 传递给 mode 。顺序设备 (譬如：stdin 和 stdout) 不受此局限性的影响。
需要启用对控制台应用程序的支持，为在控制台使用 stdin (标准输入)、stdout (标准输出) 及 stderr (标准错误) 流。要做到这，把以下声明添加到应用程序工程文件：
CONFIG += console
另请参阅 close ().
这是重载函数。
打开现有文件描述符
fd
以给定
mode
.
handleFlags
可以用于指定额外选项。返回
true
若成功；否则返回
false
.
当 QFile 是使用此函数打开的，行为对于 close () 的控制是通过 AutoCloseHandle 标志。若 AutoCloseHandle 有指定，且此函数成功，那么调用 close () 会关闭采纳句柄。否则， close () 不会实际关闭文件，而仅刷新它。
警告：
若
fd
不是常规文件，如为 0 (
stdin
), 1 (
stdout
)，或 2 (
stderr
)，可能无法
seek
()。在此情况下，
size
() 返回
0
。见
QIODevice::isSequential
() 了解更多信息。
警告： 由于此函数打开文件不用指定文件名，所以，无法使用此 QFile 采用 QFileInfo .
另请参阅 close ().
[override virtual]
QFileDevice::Permissions
QFile::
permissions
() const
重实现： QFileDevice::permissions() const .
另请参阅 setPermissions ().
[static]
QFileDevice::Permissions
QFile::
permissions
(const
QString
&
fileName
)
这是重载函数。
返回完整 OR 在一起的组合 QFile::Permission 为 fileName .
[static, since 6.0]
QFileDevice::Permissions
QFile::
permissions
(const
std::filesystem::path
&
filename
)
这是重载函数。
该函数在 Qt 6.0 引入。
移除文件指定通过
fileName
()。返回
true
若成功；否则返回
false
.
文件被关闭，在移除它之前。
另请参阅 setFileName ().
[static]
bool
QFile::
remove
(const
QString
&
fileName
)
这是重载函数。
移除文件指定通过 fileName 给定。
返回
true
若成功；否则返回
false
.
另请参阅 remove ().
重命名文件目前指定通过
fileName
() 到
newName
。返回
true
若成功；否则返回
false
.
若文件采用名称
newName
已存在，rename() 返回
false
(即，
QFile
不会覆写它)。
文件关闭，在重命名之前。
若重命名操作失败，Qt 将试图把此文件的内容拷贝到 newName ，然后移除此文件，仅保持 newName 。若该拷贝操作失败 (或无法移除此文件)，目的地文件 newName 被移除以还原旧状态。
另请参阅 setFileName ().
[static]
bool
QFile::
rename
(const
QString
&
oldName
, const
QString
&
newName
)
这是重载函数。
重命名文件
oldName
to
newName
。返回
true
若成功；否则返回
false
.
若文件采用名称
newName
已存在，rename() 返回
false
(即，
QFile
不会覆写它)。
另请参阅 rename ().
[since 6.0]
bool
QFile::
rename
(const
std::filesystem::path
&
newName
)
这是重载函数。
该函数在 Qt 6.0 引入。
[override virtual]
bool
QFile::
resize
(
qint64
sz
)
重实现： QFileDevice::resize (qint64 sz).
[static]
bool
QFile::
resize
(const
QString
&
fileName
,
qint64
sz
)
这是重载函数。
设置
fileName
到大小 (以字节为单位)
sz
。返回
true
若重置大小成功；否则 false。若
sz
>
fileName
目前是新字节数将被设为 0，若
sz
更小，只需截取文件。
警告： 此函数可能失败，若文件不存在。
另请参阅 resize ().
设置 name 为文件。名称可以没有路径、相对路径或绝对路径。
不要调用此函数，若文件已打开。
若文件名没有路径 (或相对路径)，使用的路径将是应用程序的当前目录路径 当 open () 调用。
范例：
QFile file; QDir::setCurrent("/tmp"); file.setFileName("readme.txt"); QDir::setCurrent("/home"); file.open(QIODevice::ReadOnly); // opens "/home/readme.txt" under Unix
注意，目录分隔符 / 工作于由 Qt 支持的所有操作系统。
另请参阅 fileName (), QFileInfo ，和 QDir .
[since 6.0]
void
QFile::
setFileName
(const
std::filesystem::path
&
name
)
这是重载函数。
该函数在 Qt 6.0 引入。
[override virtual]
bool
QFile::
setPermissions
(
QFileDevice::Permissions
permissions
)
重实现： QFileDevice::setPermissions (QFileDevice::Permissions permissions).
将文件权限设为
permissions
指定。返回
true
若成功，或
false
若权限不能被修改。
警告： 此函数不操纵 ACL (访问控制列表)，这可能限制其有效性。
另请参阅 permissions () 和 setFileName ().
[static]
bool
QFile::
setPermissions
(const
QString
&
fileName
,
QFileDevice::Permissions
permissions
)
这是重载函数。
设置权限为 fileName 文件到 permissions .
[static, since 6.0]
bool
QFile::
setPermissions
(const
std::filesystem::path
&
filename
,
QFileDevice::Permissions
permissionSpec
)
这是重载函数。
该函数在 Qt 6.0 引入。
[override virtual]
qint64
QFile::
size
() const
重实现： QFileDevice::size() const .
[static]
QString
QFile::
symLinkTarget
(const
QString
&
fileName
)
返回符号链接 (或 Windows 快捷方式) 引用文件 (或目录) 的绝对路径指定通过 fileName ，或返回空字符串若 fileName 不对应于符号链接。
此名称可能不表示现有文件；它只是字符串。
QFile::exists
() 返回
true
若符号链接指向现有文件。
这是重载函数。
返回符号链接 (或 Windows 快捷方式) 指向文件 (或目录) 的绝对路径，或空字符串若对象不是符号链接。
此名称可能不表示现有文件；它只是字符串。
QFile::exists
() 返回
true
若符号链接指向现有文件。
另请参阅 fileName () 和 setFileName ().