En esta página

QSaveFile Class

La clase QSaveFile ofrece una interfaz para escribir en archivos de forma segura. Más información...

Encabezado: #include <QSaveFile>
CMake: find_package(Qt6 REQUIRED COMPONENTS Core)
target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake: QT += core
Heredado de: QFileDevice

Nota: Todas las funciones de esta clase son reentrantes.

Funciones públicas

QSaveFile(QObject *parent = nullptr)
QSaveFile(const QString &name, QObject *parent = nullptr)
(since 6.11) QSaveFile(const std::filesystem::path &path, QObject *parent = nullptr)
virtual ~QSaveFile()
void cancelWriting()
bool commit()
bool directWriteFallback() const
(since 6.11) std::filesystem::path filesystemFileName() const
void setDirectWriteFallback(bool enabled)
void setFileName(const QString &name)
(since 6.11) void setFileName(const std::filesystem::path &name)

Funciones públicas reimplementadas

virtual QString fileName() const override
virtual bool open(QIODeviceBase::OpenMode mode) override
(since 6.12) virtual QFileDevice::Permissions permissions() const override
(since 6.12) virtual bool setPermissions(QFileDevice::Permissions permissions) override

Funciones protegidas reimplementadas

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

Descripción detallada

QSaveFile es un dispositivo de E/S para escribir archivos de texto y binarios, sin perder los datos existentes si falla la operación de escritura.

Durante la escritura, el contenido se guardará en un archivo temporal y, si no se produce ningún error, commit() lo trasladará al archivo definitivo. Esto garantiza que no se pierdan datos en el archivo definitivo en caso de que se produzca un error durante la escritura, y que nunca haya un archivo parcialmente escrito en la ubicación definitiva. Utiliza siempre QSaveFile al guardar documentos completos en el disco.

QSaveFile detecta automáticamente los errores durante la escritura, como el caso de que la partición esté llena, en el que write() no puede escribir todos los bytes. Recordará que se ha producido un error y descartará el archivo temporal en commit().

Al igual que con ` QFile`, el archivo se abre con ` open()`. Los datos suelen leerse y escribirse utilizando ` QDataStream ` o ` QTextStream`, pero también se puede llamar directamente a ` write()`.

A diferencia de QFile, no está permitido llamar a close(). commit() lo sustituye. Si no se ha llamado a commit() y se destruye la instancia de QSaveFile, el archivo temporal se descarta.

Para abortar el guardado debido a un error de la aplicación, llama a ` cancelWriting()`, de modo que ni siquiera una llamada posterior a ` commit()` guarde los datos.

Véase también QTextStream, QDataStream, QFileInfo, QDir, QFile y QTemporaryFile.

Documentación de funciones de miembro

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

Crea un nuevo objeto de archivo con el ` parent` indicado. Es necesario llamar a ` setFileName()` antes de ` open()`.

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

Crea un nuevo objeto de archivo con la propiedad « parent » indicada para representar el archivo con la propiedad « name » especificada.

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

Crea un nuevo objeto de archivo con el ` parent ` proporcionado para representar el archivo con el ` path` especificado.

Esta función se introdujo en Qt 6.11.

[virtual noexcept] QSaveFile::~QSaveFile()

Destruye el objeto de archivo, descartando el contenido guardado, a menos que se haya llamado a commit().

void QSaveFile::cancelWriting()

Cancela la escritura del nuevo archivo.

Si la aplicación cambia de opinión durante el proceso de guardado, puede llamar a `cancelWriting()`, que establece un código de error para que ` commit()` descarte el archivo temporal.

Como alternativa, simplemente puede asegurarse de no llamar a commit().

Es posible realizar más operaciones de escritura tras llamar a este método, pero ninguna de ellas tendrá efecto alguno, ya que el archivo escrito se descartará.

Este método no tiene ningún efecto cuando se utiliza el modo de escritura directa. Este es el caso al guardar sobre un archivo existente en un directorio de solo lectura: no se puede crear ningún archivo temporal, por lo que el archivo existente se sobrescribe en cualquier caso, y cancelWriting() no puede hacer nada al respecto; el contenido del archivo existente se perderá.

Véase también ` commit()`.

bool QSaveFile::commit()

Guarda los cambios en el disco, siempre que todas las operaciones de escritura anteriores se hayan realizado correctamente.

Es obligatorio llamar a esta función al final de la operación de guardado; de lo contrario, el archivo se descartará.

Si se ha producido un error durante la escritura, elimina el archivo temporal y devuelve ` false`. De lo contrario, le cambia el nombre por el definitivo ` fileName ` y devuelve ` true ` si se realiza correctamente. Por último, cierra el dispositivo.

Véase también ` cancelWriting()`.

bool QSaveFile::directWriteFallback() const

Devuelve « true » si está habilitada la solución alternativa para guardar archivos en directorios de solo lectura.

Véase también setDirectWriteFallback().

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

Reimplementa: ` QFileDevice::fileName()` const.

Devuelve el nombre establecido mediante setFileName() o en el constructor QSaveFile.

Véase también setFileName().

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

Devuelve ` fileName()` como ` std::filesystem::path`.

Esta función se introdujo en Qt 6.11.

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

Reimplementa: QIODevice::open(modo QIODeviceBase::OpenMode).

Abre el archivo utilizando los indicadores de mode especificados.

Devuelve ` true ` si se realiza correctamente; en caso contrario, devuelve ` false`.

Importante: Los indicadores de mode deben incluir QIODeviceBase::WriteOnly. Otros indicadores comunes que se pueden utilizar son Text y Unbuffered. Los indicadores que no se admiten actualmente son ReadOnly (y, por lo tanto, ReadWrite), Append, NewOnly y ExistingOnly; generarán una advertencia en tiempo de ejecución.

Véase también setFileName() y QT_USE_NODISCARD_FILE_OPEN.

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

Reimplementa: ` QFileDevice::permissions()` const.

Informa de los permisos que se otorgarán al archivo si se ejecuta correctamente commit().

Esta función se introdujo en Qt 6.12.

Véase también setPermissions().

void QSaveFile::setDirectWriteFallback(bool enabled)

Permite sobrescribir el archivo existente si es necesario.

QSaveFile Crea un archivo temporal en el mismo directorio que el archivo final y le cambia el nombre de forma atómica. Sin embargo, esto no es posible si los permisos del directorio no permiten crear nuevos archivos. Para preservar las garantías de atomicidad, la función ` open()` falla cuando no puede crear el archivo temporal.

Para permitir a los usuarios editar archivos con permisos de escritura en un directorio con permisos restringidos, llama a `setDirectWriteFallback()` con ` enabled ` establecido en `true`, y las siguientes llamadas a ` open()` recurrirán a abrir directamente el archivo existente y escribir en él, sin utilizar un archivo temporal. Esto no garantiza la atomicidad; es decir, un fallo de la aplicación o, por ejemplo, un corte de corriente podrían dar lugar a que el archivo quedara parcialmente escrito en el disco. También significa que, en tal caso, la función ` cancelWriting()` no surtirá efecto.

Por lo general, para guardar documentos editados por el usuario, llama a `setDirectWriteFallback(true)`, y para guardar archivos internos de la aplicación (archivos de configuración, archivos de datos, etc.), mantén la configuración predeterminada, que garantiza la atomicidad.

Véase también directWriteFallback().

void QSaveFile::setFileName(const QString &name)

Establece el nombre del archivo ( name ). El nombre puede no incluir ninguna ruta, ser una ruta relativa o una ruta absoluta.

Véase también QFile::setFileName() y fileName().

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

Esta es una función sobrecargada.

Esta función se introdujo en Qt 6.11.

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

Reimplementa: ` QFileDevice::setPermissions` (permisos de `QFileDevice::Permissions`).

Establece el permissions que se asignará al archivo tras una llamada exitosa a commit().

Aunque se escriba mediante QSaveFile, el archivo puede tener permisos más restrictivos.

Esta función se introdujo en Qt 6.12.

Véase también ` permissions()`.

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

Reimplementa: QFileDevice::writeData(const char *data, qint64 len).

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.