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)

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

该文件在复制前已关闭。

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

如果复制成功，则返回true ；否则返回false 。

请注意，如果名称为newName 的文件已经存在，copy() 将返回false 。这意味着QFile 不会覆盖该文件。

另请参阅 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)

这是一个重载函数。

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

该文件在复制前已关闭。

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

如果复制成功，则返回true ；否则返回false 。

请注意，如果名称为newName 的文件已经存在，copy() 将返回false 。这意味着QFile 不会覆盖该文件。

另请参阅 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() 常量。

返回由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）。

使用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 传递给 ，Qt 将翻译行结束字符。顺序设备（如 stdin 和 stdout）不受此限制的影响。mode

要在控制台使用 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() 常量。

另请参见 setPermissions().

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

这是一个重载函数。

返回fileName 的 QFile::Permission 的完整 OR-ed together 组合。

[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 XML 会尝试将此文件的内容复制到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）。

将文件的权限设置为指定的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 XML 支持在当前操作系统中使用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()。