QSaveFile Class

成员函数文档

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

使用给定的parent 创建一个新的文件对象。在调用open()之前，需要先调用setFileName()。

[explicit] QSaveFile::QSaveFile(const QString &name, QObject *parent = nullptr)

使用给定的parent 构建一个新的文件对象，以表示具有指定name 的文件。

[since 6.11] QSaveFile::QSaveFile(const std::filesystem::path &path, QObject *parent = nullptr)

使用给定的parent 构建一个新的文件对象，以表示具有指定path 的文件。

该函数于 Qt 6.11 中引入。

[virtual noexcept] QSaveFile::~QSaveFile()

销毁文件对象，并丢弃已保存的内容，除非已调用commit()。

void QSaveFile::cancelWriting()

取消写入新文件。

如果应用程序在保存过程中改变了主意，可以调用 cancelWriting()，该函数会设置一个错误代码，从而使commit() 丢弃临时文件。

或者，应用程序也可以直接确保不调用commit()。

调用此方法后仍可进行进一步的写入操作，但这些操作均不会产生任何效果，已写入的文件将被丢弃。

当使用直接写入回退时，此方法无效。例如，在只读目录中覆盖现有文件时：由于无法创建临时文件，因此无论如何都会覆盖现有文件，cancelWriting() 对此无能为力，现有文件的内容将会丢失。

另请参阅 commit()。

bool QSaveFile::commit()

如果之前的所有写入操作均成功，则将更改提交到磁盘。

必须在保存操作结束时调用此方法，否则文件将被丢弃。

如果写入过程中发生错误，则删除临时文件并返回false 。否则，将其重命名为最终的fileName ，并在成功时返回true 。最后，关闭设备。

另请参阅 cancelWriting()。

bool QSaveFile::directWriteFallback() const

如果启用了在只读目录中保存文件的备用方案，则返回true 。

另请参阅 setDirectWriteFallback()。

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

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

返回由 `setFileName()` 或 `QSaveFile ` 构造函数设置的名称。

另请参阅 setFileName()。

[since 6.11] std::filesystem::path QSaveFile::filesystemFileName() const

返回fileName()，其值为std::filesystem::path 。

该函数在 Qt 6.11 中引入。

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

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

使用给定的mode 标志打开文件。

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

重要提示：mode 的标志必须包含QIODeviceBase::WriteOnly 。其他可用的常见标志包括Text 和Unbuffered 。目前不支持的标志包括ReadOnly （因此也不支持ReadWrite ）、Append 、NewOnly 和ExistingOnly ；使用这些标志会引发运行时警告。

另请参阅 setFileName() 和QT_USE_NODISCARD_FILE_OPEN 。

[override virtual, since 6.12] QFileDevice::Permissions QSaveFile::permissions() const

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

在 `commit()` 调用成功后，报告应授予该文件的权限。

该函数在 Qt 6.12 中引入。

另请参阅 setPermissions()。

void QSaveFile::setDirectWriteFallback(bool enabled)

如有必要，允许覆盖现有文件。

QSaveFile 在目标文件所在的同一目录中创建一个临时文件，并以原子方式对其进行重命名。但如果目录权限不允许创建新文件，则无法执行此操作。为了保持原子性保证，当无法创建临时文件时，open() 会返回失败。

为了允许用户在权限受限的目录中编辑具有写入权限的文件，请调用 setDirectWriteFallback() 并将enabled 设置为 true；此后对open() 的调用将回退为直接打开现有文件并写入其中，而不会使用临时文件。 此方法无法保证原子性，即应用程序崩溃或断电等情况可能导致磁盘上出现未写完全的文件。这也意味着在这种情况下，cancelWriting() 将不起作用。

通常，要保存用户编辑的文档，请调用 setDirectWriteFallback(true)；而要保存应用程序内部文件（配置文件、数据文件等），请保留默认设置以确保原子性。

另请参阅 directWriteFallback()。

void QSaveFile::setFileName(const QString &name)

设置文件的name 。文件名可以不包含路径、包含相对路径或包含绝对路径。

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

[since 6.11] void QSaveFile::setFileName(const std::filesystem::path &name)

该函数在 Qt 6.11 中引入。

[override virtual, since 6.12] bool QSaveFile::setPermissions(QFileDevice::Permissions permissions)

重写了：QFileDevice::setPermissions （QFileDevice::Permissions 权限）。

设置在成功调用 `commit()` 后，应赋予该文件的 `permissions `。

通过QSaveFile 写入文件时，该文件的权限可能更为严格。

此函数在 Qt 6.12 中引入。

另请参阅 permissions()。

[override virtual protected] qint64 QSaveFile::writeData(const char *data, qint64 len)

重新实现了：QFileDevice::writeData(const char *data, qint64 len)。