QFile Class

成员函数文档

QFile::QFile()

创建一个 QFile 对象。

[explicit] QFile::QFile(QObject *parent)

使用给定的parent 创建一个新的文件对象。

[explicit] QFile::QFile(const QString &name)

创建一个新的文件对象，用于表示具有给定name 的文件。

[explicit, since 6.0] QFile::QFile(const std::filesystem::path &name)

创建一个新的文件对象，用于表示指定文件name 。

该函数于 Qt 6.0 中引入。

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 中引入。

[virtual noexcept] QFile::~QFile()

销毁文件对象，并在必要时将其关闭。

bool QFile::copy(const QString &newName, std::optional<QFileDevice::Permissions> perm = std::nullopt)

将名为fileName()的文件复制到newName 。

该文件在复制前会被关闭。

自 Qt 6.12 起，调用时可以指定权限perm 。若未传入该参数，则复制源文件的权限。新文件将按给定的权限创建。

如果复制的文件是一个符号链接（symlink），则复制的是它所指向的文件，而不是链接本身。除权限外，其他文件元数据均不被复制。

若操作成功，返回true ；否则返回false 。

请注意，如果已存在名为newName 的文件，copy() 将返回false 。这意味着QFile 不会覆盖该文件。但是，此操作并非原子操作。在检查与复制之间，可能有其他进程创建了名为newName 的文件。在这种情况下，该文件将被覆盖。

另请参阅 setFileName()。

[since 6.0] bool QFile::copy(const std::filesystem::path &newName)

该函数在 Qt 6.0 中引入。

[static] bool QFile::copy(const QString &fileName, const QString &newName, std::optional<QFileDevice::Permissions> perm = std::nullopt)

将名为fileName 的文件复制到newName 。

自 Qt 6.12 起，调用时可以指定权限perm 。若未传入该参数，则复制源文件的权限。新文件将按给定的权限创建。

如果被复制的文件是符号链接（symlink），则复制的是它所指向的文件，而不是链接本身。除权限外，其他文件元数据均不会被复制。

若操作成功，则返回true ；否则返回false 。

请注意，如果已存在名为newName 的文件，copy() 将返回false 。这意味着QFile 不会覆盖该文件。但是，此操作并非原子操作。在检查与复制之间，存在其他进程创建名为newName 的文件的可能性。在这种情况下，该文件将被覆盖。

另请参阅 rename()。

[static] QString QFile::decodeName(const QByteArray &localFileName)

这通过localFileName 实现了与QFile::encodeName() 相反的功能。

另请参阅 encodeName()。

[static] QString QFile::decodeName(const char *localFileName)

返回给定localFileName 的Unicode版本。详情请参阅encodeName()。

[static] QByteArray QFile::encodeName(const QString &fileName)

将fileName 转换为可在本机API中使用的8位编码。在Windows系统上，该编码采用当前活动的Windows（ANSI）代码页；在其他平台上，则采用UTF-8编码，而在macOS系统上则采用分解形式（NFD）。

另请参阅 decodeName()。

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

如果由 `fileName ` 指定的文件存在，则返回 `true `；否则返回 `false`。

bool QFile::exists() const

如果由fileName()指定的文件存在，则返回true ；否则返回false 。

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

[override virtual] QString QFile::fileName() const

重写了：QFileDevice::fileName() const。

返回由setFileName()、rename() 或QFile 构造函数设置的文件名。

另请参阅 setFileName()、rename()，以及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() 作为fileName 的std::filesystem::path 。

该函数于 Qt 6.3 中引入。

bool QFile::link(const QString &linkName)

创建一个名为linkName 的链接，该链接指向当前由fileName()指定的文件。链接的具体形式取决于底层文件系统（在Windows上可能是快捷方式，在Unix上可能是符号链接）。若操作成功，则返回true ；否则返回false 。

该函数不会覆盖文件系统中已存在的实体；在此情况下，link() 将返回false，并设置error()返回RenameError 。

另请参阅 setFileName()。

[since 6.0] bool QFile::link(const std::filesystem::path &newName)

该函数在 Qt 6.0 中引入。

[static] bool QFile::link(const QString &fileName, const QString &linkName)

创建一个名为linkName 的链接，该链接指向文件fileName 。链接的具体形式取决于底层文件系统（在 Windows 上可能是快捷方式，在 Unix 上可能是符号链接）。如果操作成功，则返回true ；否则返回false 。

另请参阅 link()。

bool QFile::moveToTrash()

将由fileName()指定的文件移至垃圾桶。若操作成功，则返回true ，并将fileName()设置为该文件在垃圾桶中的路径；否则返回false 。

此函数的执行时间与被移入垃圾桶的文件大小无关。如果对目录调用此函数，其执行时间可能与被移入垃圾桶的文件数量成正比。如果当前的fileName()指向一个符号链接，此函数将把该链接移入垃圾桶（这可能会导致链接失效），而非其目标文件。

在 Windows 和 macOS 操作系统上，本函数使用相应的 API 执行文件移入回收站操作。在其他系统（Unix 系统）上，本函数遵循FreeDesktop.org 回收站规范 1.0 版。

另请参阅 supportsMoveToTrash()、remove() 和QDir::remove()。

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

将fileName 指定的文件移至废纸篓。若操作成功，则返回true ，并将pathInTrash （若已提供）设置为该文件在废纸篓中的路径；否则返回false 。

此函数的执行时间与被移入垃圾桶的文件大小无关。若对目录调用此函数，其执行时间可能与被移入垃圾桶的文件数量成正比。如果当前的fileName() 指向一个符号链接，此函数将把该链接移入垃圾桶（这可能会导致链接失效），而非其链接目标。

在 Windows 和 macOS 操作系统上，该函数使用相应的 API 执行文件移入回收站操作。在其他系统（Unix 系统）上，该函数遵循FreeDesktop.org 回收站规范 1.0 版。

[override virtual] bool QFile::open(QIODeviceBase::OpenMode mode)

重写了：QIODevice::open （QIODeviceBase::OpenMode 模式）。

使用mode 标志打开文件，若成功则返回true ；否则返回false 。

mode 的标志必须包含QIODeviceBase::ReadOnly 、WriteOnly 或ReadWrite 。此外还可以包含其他标志，例如Text 和Unbuffered 。

另请参阅 QT_USE_NODISCARD_FILE_OPEN 和setFileName()。

[since 6.3] bool QFile::open(QIODeviceBase::OpenMode mode, QFileDevice::Permissions permissions)

如果文件不存在，且mode 表示需要创建该文件，则会使用指定的permissions 创建该文件。

在 POSIX 系统上，实际权限受umask 值的影响。

在 Windows 上，权限是通过访问控制列表 (ACL) 模拟的。当组被授予的权限少于“其他人”时，这些 ACL 的顺序可能不符合标准。具有此类权限的文件和目录在打开“属性”对话框的“安全”选项卡时会生成警告。向组授予与“其他人”相同的全部权限可避免此类警告。

该函数在 Qt 6.3 中引入。

另请参阅 QIODevice::OpenMode 、setFileName() 以及QT_USE_NODISCARD_FILE_OPEN 。

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

在指定的mode 中打开现有文件句柄fh 。可使用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 在访问文件和其他随机访问设备时，必须以二进制模式打开（即模式字符串必须包含 'b'，如 "rb" 或 "wb"）。 如果您将 QIODevice::Text 传递给mode ，Qt 会转换行尾字符。顺序设备（如 stdin 和 stdout）不受此限制的影响。

若要在控制台使用 stdin、stdout 和 stderr 流，您需要启用对控制台应用程序的支持。为此，请在应用程序的项目文件中添加以下声明：

CONFIG += console

另请参阅 close() 和QT_USE_NODISCARD_FILE_OPEN 。

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

在指定的mode 中打开现有的文件描述符fd 。可使用handleFlags 指定其他选项。若操作成功，则返回true ；否则返回false 。

当使用此函数打开QFile 时，close() 的行为由 AutoCloseHandle 标志控制。如果指定了 AutoCloseHandle，且此函数执行成功，则调用close() 将关闭该已采用的句柄。否则，close() 实际上不会关闭文件，而只是刷新文件。

另请参阅 close() 和QT_USE_NODISCARD_FILE_OPEN 。

[override virtual] QFileDevice::Permissions QFile::permissions() const

重新实现了：QFileDevice::permissions() const。

另请参见 setPermissions()。

[static] QFileDevice::Permissions QFile::permissions(const QString &fileName)

返回fileName 的QFile::Permission的完整“或”运算组合。

[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()。

[since 6.0] bool QFile::rename(const std::filesystem::path &newName)

该函数在 Qt 6.0 中引入。

[static] bool QFile::rename(const QString &oldName, const QString &newName)

将文件oldName 重命名为newName 。成功时返回true ；否则返回false 。

如果已经存在名为newName 的文件，rename() 将返回false （即QFile 不会覆盖该文件）。

另请参阅 rename()。

[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 。如果成功，则返回true ；如果无法修改权限，则返回false 。

另请参阅 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, since 6.9] bool QFile::supportsMoveToTrash()

如果 Qt 支持在当前操作系统中使用moveToTrash() 函数将文件移至垃圾桶（回收站），则返回true ；否则返回false 。请注意，该函数返回true 并不意味着moveToTrash() 一定会成功。特别是，该函数不会检查用户是否已在设置中禁用了此功能。

该函数于 Qt 6.9 中引入。

另请参阅 moveToTrash()。

[static] QString QFile::symLinkTarget(const QString &fileName)

返回由fileName 指定的符号链接（或 Windows 中的快捷方式）所指向的文件或目录的绝对路径；如果fileName 不对应于符号链接，则返回空字符串。

该名称可能并不代表一个现有文件；它仅是一个字符串。如果符号链接指向一个现有文件，QFile::exists() 将返回true 。

QString QFile::symLinkTarget() const

返回符号链接（或 Windows 中的快捷方式）所指向的文件或目录的绝对路径；如果该对象不是符号链接，则返回一个空字符串。

该名称可能并不代表一个现有的文件；它仅仅是一个字符串。如果符号链接指向一个现有的文件，QFile::exists() 将返回true 。

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