QSaveFile 类

QSaveFile 类提供了一个安全写入文件的接口，如果在写入操作失败时通常会保留现有数据。更多信息...

头文件	#include <QSaveFile>
CMake	find_package(Qt6 REQUIRED COMPONENTS Core) target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake	QT += core
继承自	QFileDevice

所有成员列表，包括继承的成员
QSaveFile 是输入/输出和网络的一部分。

注意： 该类中所有函数都是可重入的。

公共函数

	QSaveFile(const QString &name)
	QSaveFile(QObject *parent = nullptr)
	QSaveFile(const QString &name, QObject *parent)
virtual	~QSaveFile()
void	cancelWriting()
bool	commit()
bool	directWriteFallback() const
void	setDirectWriteFallback(bool enabled)
void	setFileName(const QString &name)

重写的公共函数

virtual QString	fileName() const override
virtual bool	open(QIODeviceBase::OpenMode mode) override

重写的受保护函数

virtual qint64 writeData(const char *data, qint64 len) override

详细描述

QSaveFile 是一个用于写入文本和二进制文件的 I/O 设备，如果在写入操作失败时通常会保留现有数据。

写入时，内容将写入一个临时文件，如果没有发生错误，则 commit() 将将其移动到最终文件。这确保了如果在写入过程中发生错误，最终文件中不会丢失数据，并且绝对无法在任何最终位置出现部分写入的文件。在将整个文档保存到磁盘时，始终使用 QSaveFile。

QSaveFile 在写入时自动检测错误，例如全分区情况，其中 write() 无法写入所有字节。它将记住发生了错误，并在 commit() 中丢弃临时文件。

与 QFile 类似，文件通过 open() 打开。数据通常使用 QDataStream 或 QTextStream 读取和写入，但也可以调用继承的 QIODevice 函数 read()、readLine()、readAll()、write()。

与QFile不同，不允许调用close()。而是用commit()来代替。如果没有调用commit()且QSaveFile实例被销毁，临时文件将被丢弃。

如果要因应用程序错误而中止保存，请调用cancelWriting()，这样即使稍后调用commit()，也不会保存。

另请参阅QTextStream、QDataStream、QFileInfo、QDir、QFile和QTemporaryFile。

成员函数文档

`[显式]` QSaveFile::QSaveFile(const QString &name)

构建一个新的文件对象来表示具有给定name的文件。

`[显式]` QSaveFile::QSaveFile(QObject **parent* = nullptr)

构建一个新的文件对象，具有给定的parent。

`[显式]` QSaveFile::QSaveFile(const QString &name, QObject **parent*)

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

`[虚拟 noexcept]` QSaveFile::~QSaveFile()

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

void QSaveFile::cancelWriting()

取消写入新文件。

如果在保存过程中应用程序改变主意，可以调用cancelWriting()，这会设置一个错误码，使得稍后调用commit()会丢弃临时文件。

或者，确保不调用commit()。

调用此方法后仍可以进行进一步写入操作，但它们都不会产生任何效果，所写入的文件将被丢弃。

此方法在直接写入回退模式下没有效果。这发生在将现有文件保存到只读目录时：无法创建临时文件，因此无论发生什么情况，都会覆盖现有文件，并且取消写入 nothing 能对这种情况做什么，现有文件的内容将会丢失。

另请参阅commit。

bool QSaveFile::commit()

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

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

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

另请参阅cancelWriting。

bool QSaveFile::directWriteFallback() const

如果启用了保存文件到只读目录的回退解决方案，则返回true。

另请参阅setDirectWriteFallback。

`[覆盖虚函数]` QString QSaveFile::fileName() const

重新实现: QFileDevice::fileName() const.

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

另请参阅 setFileName().

`[覆盖虚函数]` bool QSaveFile::open(QIODeviceBase::OpenMode mode)

重新实现: QIODevice::open(QIODeviceBase::OpenMode mode).

使用 mode OpenMode 打开文件，如果成功则返回 true，否则返回 false。

重要：模式 mode 必须包括 QIODevice::WriteOnly。它也可以有其他标志，例如 QIODevice::Text 和 QIODevice::Unbuffered。

目前不支持 QIODevice::ReadWrite、QIODevice::Append、QIODevice::NewOnly 和 QIODevice::ExistingOnly。

另请参阅 QIODevice::OpenMode 和 setFileName().

void QSaveFile::setDirectWriteFallback(bool enabled)

允许在需要时覆盖现有文件。

如果目录权限不允许创建新文件，QSaveFile 创建与最终文件同一目录的临时文件并将其原子性地重命名。然而，如果目录权限不允许创建新文件，这不可能实现。为了保留原子性保证，如果在无法创建临时文件时调用 open()，则将失败。

为了允许用户在权限受限的目录中编辑具有写权限的文件，将 enabled 设置为 true 并调用 setDirectWriteFallback()，并且后续对 open() 的调用将回退到直接打开现有文件并写入，而不使用临时文件。这没有原子性保证，也就是说应用程序崩溃或例如电源故障可能导致磁盘上出现部分写入的文件。这也意味着在这种情况下，cancelWriting() 没有作用。

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

另请参阅 directWriteFallback().

void QSaveFile::setFileName(const QString &name)

设置文件名。该名称可以是名称，相对路径或绝对路径。

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

`[覆盖虚保护函数]` qint64 QSaveFile::writeData(const char **data, qint64 len*)

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