QFile 类

QFile 类提供用于读写文件的接口。 更多...

头：	#include <QFile>
CMake:	find_package(Qt6 REQUIRED COMPONENTS Core) target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake:	QT += core
继承：	QFileDevice
继承者：	QTemporaryFile

• 所有成员列表，包括继承成员
• QFile 属于 输入/输出和网络 .

注意： 此类的所有函数 可重入 .

公共函数

	QFile ()
	QFile (const QString & name )
	QFile (const std::filesystem::path & name )
	QFile (QObject * parent )
	QFile (const QString & name , QObject * parent )
	QFile (const std::filesystem::path & name , QObject * parent )
virtual	~QFile ()
bool	copy (const QString & newName )
bool	copy (const std::filesystem::path & newName )
bool	exists () const
std::filesystem::path	filesystemFileName () const
std::filesystem::path	filesystemSymLinkTarget () const
bool	link (const QString & linkName )
bool	link (const std::filesystem::path & newName )
bool	moveToTrash ()
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 )
bool	rename (const std::filesystem::path & newName )
void	setFileName (const QString & name )
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 )
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 )
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 )
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 (统一资源标识符) :

• 可能需要提示用户的访问权限透过 QFileDialog which implements Android's native file picker.
• 目标是遵循 作用域存储 指导方针 (譬如：使用 App 特定目录，而不是其它公共外部目录)。更多信息，另请参阅 存储最佳实践 .
• 由于 Qt API (如 QFile) 的设计，是不可能的，完全集成后者 API 与 Android 的 MediaStore API。

另请参阅 QTextStream , QDataStream , QFileInfo , QDir ，和 Qt 资源系统 .

成员函数文档编制

QFile:: QFile ()

构造 QFile 对象。

QFile:: QFile (const QString & name )

构造新文件对象以表示文件采用给定 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 .

QFile:: QFile (const QString & name , QObject * parent )

构造新文件对象采用给定 parent 表示文件采用指定 name .

[since 6.0] QFile:: QFile (const std::filesystem::path & name , QObject * parent )

构造新文件对象采用给定 parent 表示文件采用指定 name .

该函数在 Qt 6.0 引入。

[虚拟] QFile:: ~QFile ()

销毁文件对象，关闭它若有必要。

bool QFile:: copy (const QString & newName )

拷贝文件命名 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。

bool QFile:: exists () const

这是重载函数。

返回 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 引入。

bool QFile:: link (const QString & linkName )

创建链接命名 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 引入。

bool QFile:: moveToTrash ()

移动指定文件按 fileName () 到垃圾桶。返回 true 若成功，并设置 fileName () 为可以在垃圾桶中找到的文件路径；否则返回 false .

注意： 在系统 API 不报告垃圾桶中文件位置的系统中， fileName () 会被设为 null 字符串，一旦移动文件。在没有垃圾桶的系统中，此函数始终返回 false。

[static] bool QFile:: moveToTrash (const QString & fileName , QString * pathInTrash = nullptr)

这是重载函数。

移动指定文件按 fileName () 到垃圾桶。返回 true 若成功，并设置 pathInTrash (若有提供) 为可以在垃圾桶中找到的文件路径；否则返回 false .

注意： 在系统 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 ().

bool QFile:: open ( FILE * fh , QIODeviceBase::OpenMode mode , QFileDevice::FileHandleFlags handleFlags = DontCloseHandle)

这是重载函数。

打开现有文件句柄 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 () 不会实际关闭文件，而仅刷新它。

警告：

1. 若 fh 不是指常规文件，如，它是 stdin , stdout ，或 stderr ，可能无法 seek (). size () 返回 0 在此情况下。见 QIODevice::isSequential () 了解更多信息。
2. 由于此函数打开文件不用指定文件名，所以，无法使用此 QFile 采用 QFileInfo .

Windows 平台注意事项

fh 必须以二进制方式打开 (即：mode 字符串必须包含 b，如在 rb 或 wb) 当访问文件及其它随机访问设备时。Qt 将翻译行尾字符，若把 QIODevice::Text 传递给 mode 。顺序设备 (譬如：stdin 和 stdout) 不受此局限性的影响。

需要启用对控制台应用程序的支持，为在控制台使用 stdin (标准输入)、stdout (标准输出) 及 stderr (标准错误) 流。要做到这，把以下声明添加到应用程序工程文件：

CONFIG += console
					

另请参阅 close ().

bool QFile:: open ( int fd , QIODeviceBase::OpenMode mode , QFileDevice::FileHandleFlags handleFlags = DontCloseHandle)

这是重载函数。

打开现有文件描述符 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 引入。

bool QFile:: remove ()

移除文件指定通过 fileName ()。返回 true 若成功；否则返回 false .

文件被关闭，在移除它之前。

另请参阅 setFileName ().

[static] bool QFile:: remove (const QString & fileName )

这是重载函数。

移除文件指定通过 fileName 给定。

返回 true 若成功；否则返回 false .

另请参阅 remove ().

bool QFile:: rename (const QString & newName )

重命名文件目前指定通过 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 ().

void QFile:: setFileName (const QString & name )

设置 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 若符号链接指向现有文件。

QString QFile:: symLinkTarget () const

这是重载函数。

返回符号链接 (或 Windows 快捷方式) 指向文件 (或目录) 的绝对路径，或空字符串若对象不是符号链接。

此名称可能不表示现有文件；它只是字符串。 QFile::exists () 返回 true 若符号链接指向现有文件。

另请参阅 fileName () 和 setFileName ().

内容

• 公共函数

• 重实现公共函数

• 静态公共成员

• 详细描述

• 直接读取文件

• 使用流读取文件

• 信号

• 平台具体问题