QXmlStreamWriter Class
La clase QXmlStreamWriter ofrece un generador de XML 1.0 con una sencilla API de transmisión. Más información...
| Encabezado: | #include <QXmlStreamWriter> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Core) target_link_libraries(mytarget PRIVATE Qt6::Core) |
| qmake: | QT += core |
- Lista de todos los miembros, incluidos los heredados
- QXmlStreamWriter forma parte de las clases XML.
Nota: Todas las funciones de esta clase son reentrantes.
Tipos públicos
(since 6.10) enum class | Error { None, IO, Encoding, InvalidCharacter, Custom } |
Propiedades
- autoFormatting : bool
- autoFormattingIndent : int
(since 6.10)stopWritingOnError : bool
Funciones públicas
| QXmlStreamWriter() | |
| QXmlStreamWriter(QByteArray *array) | |
| QXmlStreamWriter(QIODevice *device) | |
| QXmlStreamWriter(QString *string) | |
| ~QXmlStreamWriter() | |
| bool | autoFormatting() const |
| int | autoFormattingIndent() const |
| QIODevice * | device() const |
(since 6.10) QXmlStreamWriter::Error | error() const |
(since 6.10) QString | errorString() const |
| bool | hasError() const |
(since 6.10) void | raiseError(QAnyStringView message) |
| void | setAutoFormatting(bool enable) |
| void | setAutoFormattingIndent(int spacesOrTabs) |
| void | setDevice(QIODevice *device) |
| void | setStopWritingOnError(bool stop) |
| bool | stopWritingOnError() const |
| void | writeAttribute(QAnyStringView namespaceUri, QAnyStringView name, QAnyStringView value) |
| void | writeAttribute(const QXmlStreamAttribute &attribute) |
| void | writeAttribute(QAnyStringView qualifiedName, QAnyStringView value) |
| void | writeAttributes(const QXmlStreamAttributes &attributes) |
| void | writeCDATA(QAnyStringView text) |
| void | writeCharacters(QAnyStringView text) |
| void | writeComment(QAnyStringView text) |
| void | writeCurrentToken(const QXmlStreamReader &reader) |
| void | writeDTD(QAnyStringView dtd) |
| void | writeDefaultNamespace(QAnyStringView namespaceUri) |
| void | writeEmptyElement(QAnyStringView namespaceUri, QAnyStringView name) |
| void | writeEmptyElement(QAnyStringView qualifiedName) |
| void | writeEndDocument() |
| void | writeEndElement() |
| void | writeEntityReference(QAnyStringView name) |
| void | writeNamespace(QAnyStringView namespaceUri, QAnyStringView prefix = {}) |
| void | writeProcessingInstruction(QAnyStringView target, QAnyStringView data = {}) |
| void | writeStartDocument(QAnyStringView version) |
| void | writeStartDocument(QAnyStringView version, bool standalone) |
| void | writeStartDocument() |
| void | writeStartElement(QAnyStringView namespaceUri, QAnyStringView name) |
| void | writeStartElement(QAnyStringView qualifiedName) |
| void | writeTextElement(QAnyStringView namespaceUri, QAnyStringView name, QAnyStringView text) |
| void | writeTextElement(QAnyStringView qualifiedName, QAnyStringView text) |
Descripción detallada
QXmlStreamWriter es el equivalente a QXmlStreamReader para escribir XML. Cumple con la especificación XML 1.0 y escribe documentos utilizando la sintaxis de XML 1.0, las reglas de escape y las restricciones de validez de caracteres.
Nota: No es compatible conXML 1.1. Aunque las cadenas de versión se pueden establecer manualmente en la salida, los documentos que requieran características específicas de XML 1.1, como caracteres de control adicionales, no se pueden generar utilizando esta clase.
Al igual que su clase relacionada, opera sobre un « QIODevice » especificado con « setDevice()». La API es sencilla y directa: para cada token o evento XML que se desee escribir, el «writer» proporciona una función especializada.
Se inicia un documento con writeStartDocument() y se termina con writeEndDocument(). Esto cerrará implícitamente todas las etiquetas que queden abiertas.
Las etiquetas de los elementos se abren con ` writeStartElement()` seguida de ` writeAttribute()` o ` writeAttributes()`, el contenido del elemento y, a continuación, ` writeEndElement()`. Para escribir elementos vacíos se puede utilizar una forma más breve, ` writeEmptyElement()`, seguida de ` writeAttributes()`.
El contenido de un elemento puede consistir en caracteres, referencias a entidades o elementos anidados. Se escribe con writeCharacters(), que también se encarga de escapar todos los caracteres y secuencias de caracteres prohibidos, writeEntityReference() o llamadas posteriores a writeStartElement(). Se puede utilizar un método de conveniencia, writeTextElement(), para escribir elementos terminales que no contengan nada más que texto.
El siguiente fragmento de código abreviado muestra el uso básico de la clase para escribir XML formateado con sangría:
QXmlStreamWriter stream(&output);
stream.setAutoFormatting(true);
stream.writeStartDocument();
...
stream.writeStartElement("bookmark");
stream.writeAttribute("href", "http://qt-project.org/");
stream.writeTextElement("title", "Qt Project");
stream.writeEndElement(); // bookmark
...
stream.writeEndDocument();QXmlStreamWriter se encarga de anteponer los prefijos de los espacios de nombres; lo único que hay que hacer es especificar el namespaceUri al escribir elementos o atributos. Si es necesario cumplir con determinados prefijos, se puede obligar al escritor a utilizarlos declarando los espacios de nombres manualmente mediante writeNamespace() o writeDefaultNamespace(). Como alternativa, puedes omitir la compatibilidad con espacios de nombres del escritor de flujo y utilizar métodos sobrecargados que acepten un nombre calificado. El espacio de nombres http://www.w3.org/XML/1998/namespace es implícito y se asigna al prefijo xml.
El escritor de flujos puede formatear automáticamente los datos XML generados añadiendo saltos de línea y sangría a las secciones vacías entre elementos, lo que hace que los datos XML sean más legibles para los usuarios y más fáciles de manejar para la mayoría de los sistemas de gestión de código fuente. Esta función se puede activar con la propiedad autoFormatting y personalizar con la propiedad autoFormattingIndent.
Otras funciones son ` writeCDATA()`, ` writeComment()`, ` writeProcessingInstruction()` y ` writeDTD()`. El encadenamiento de flujos XML es compatible con ` writeCurrentToken()`.
QXmlStreamWriter siempre codifica el XML en UTF-8.
Si se produce un error durante la escritura, hasError() devolverá «true». Sin embargo, por defecto, los datos que ya se encontraban en el búfer en el momento en que se produjo el error, o los datos escritos desde dentro de la misma operación, pueden seguir escribiéndose en el dispositivo subyacente. Esto se aplica a Error::Encoding, Error::InvalidCharacter y a los errores generados por el usuario Error::Custom. Para evitarlo y garantizar que no se escriban datos tras un error, utilice la propiedad stopWritingOnError. Cuando esta propiedad está habilitada, el primer error detiene la salida inmediatamente y el escritor ignora todas las operaciones de escritura posteriores. Las aplicaciones deben tratar el estado de error como definitivo y evitar seguir utilizando el escritor tras un error.
El ejemplo «QXmlStream Bookmarks» ilustra cómo utilizar un escritor de flujo para escribir un archivo de marcadores XML (XBEL) que previamente había sido leído por un ` QXmlStreamReader`.
Documentación sobre tipos de miembros
[since 6.10] enum class QXmlStreamWriter::Error
Esta enumeración especifica los distintos casos de error que pueden producirse al escribir XML con QXmlStreamWriter.
| Constante | Valor | Descripción |
|---|---|---|
QXmlStreamWriter::Error::None | 0 | No se ha producido ningún error. |
QXmlStreamWriter::Error::IO | 1 | Se ha producido un error de E/S al escribir en el dispositivo. |
QXmlStreamWriter::Error::Encoding | 2 | Se ha producido un error de codificación al convertir los caracteres al formato de salida. |
QXmlStreamWriter::Error::InvalidCharacter | 3 | Se ha encontrado un carácter no permitido en XML 1.0 durante la escritura. |
QXmlStreamWriter::Error::Custom | 4 | Se ha generado un error personalizado con raiseError(). |
Esta enumeración se introdujo en Qt 6.10.
Documentación de la propiedad
autoFormatting : bool
Esta propiedad contiene el indicador de formato automático del escritor de flujo.
Esta propiedad controla si el escritor de flujo formatea automáticamente los datos XML generados. Si está habilitada, el escritor añade automáticamente saltos de línea y sangría a las secciones vacías entre elementos (espacios en blanco ignorables). El objetivo principal del formateo automático es dividir los datos en varias líneas y mejorar la legibilidad para el lector humano. La profundidad de sangría se puede controlar mediante la propiedad ` autoFormattingIndent `.
Por defecto, el formato automático está desactivado.
Funciones de acceso:
| bool | autoFormatting() const |
| void | setAutoFormatting(bool enable) |
autoFormattingIndent : int
Esta propiedad indica el número de espacios o tabulaciones que se utilizan para la sangría cuando está activado el formato automático. Los números positivos indican espacios, mientras que los negativos indican tabulaciones.
La sangría predeterminada es 4.
Funciones de Access:
| int | autoFormattingIndent() const |
| void | setAutoFormattingIndent(int spacesOrTabs) |
Véase también autoFormatting.
[since 6.10] stopWritingOnError : bool
Esta propiedad permite detener la escritura en el dispositivo tras detectarse un error.
Si esta propiedad se establece en « true », el escritor deja de escribir inmediatamente al detectar cualquier error e ignora todas las operaciones de escritura posteriores. Cuando esta propiedad se establece en « false », el escritor puede continuar escribiendo tras un error, omitiendo la escritura no válida pero permitiendo que se sigan realizando operaciones de salida.
Tenga en cuenta que esto incluye Error::InvalidCharacter, Error::Encoding y Error::Custom. Error::IO siempre se considera un error terminal y detiene la escritura independientemente de esta configuración.
El valor por defecto es false.
Esta enumeración se introdujo en Qt 6.10.
Funciones de acceso:
| bool | stopWritingOnError() const |
| void | setStopWritingOnError(bool stop) |
Documentación de funciones miembro
QXmlStreamWriter::QXmlStreamWriter()
Crea un escritor de flujo.
Véase también setDevice().
[explicit] QXmlStreamWriter::QXmlStreamWriter(QByteArray *array)
Crea un escritor de flujo que escribe en array. Esto equivale a crear un escritor XML que opera en un dispositivo QBuffer, el cual, a su vez, opera en array.
[explicit] QXmlStreamWriter::QXmlStreamWriter(QIODevice *device)
Crea un escritor de flujo que escribe en device;
[explicit] QXmlStreamWriter::QXmlStreamWriter(QString *string)
Crea un escritor de flujo que escribe en string.
[noexcept] QXmlStreamWriter::~QXmlStreamWriter()
Destructor.
bool QXmlStreamWriter::autoFormatting() const
Devuelve ` true ` si el formato automático está activado; en caso contrario, devuelve ` false`.
Nota: Funcióngetter para la propiedad autoFormatting.
Véase también ` setAutoFormatting()`.
QIODevice *QXmlStreamWriter::device() const
Devuelve el dispositivo actual asociado a QXmlStreamWriter, o nullptr si no se ha asignado ningún dispositivo.
Véase también setDevice().
[since 6.10] QXmlStreamWriter::Error QXmlStreamWriter::error() const
Devuelve el estado de error actual del escritor.
Si no se ha producido ningún error, esta función devuelve « QXmlStreamWriter::Error::None ».
Esta función se introdujo en Qt 6.10.
Véase también errorString(), raiseError() y hasError().
[since 6.10] QString QXmlStreamWriter::errorString() const
Si se ha producido un error, devuelve el mensaje de error asociado.
El mensaje de error lo establece internamente QXmlStreamWriter o lo proporciona el usuario mediante raiseError(). Si no se ha producido ningún error, esta función devuelve una cadena nula.
Esta función se introdujo en Qt 6.10.
Véase también error(), raiseError() y hasError().
bool QXmlStreamWriter::hasError() const
Devuelve « true » si se ha producido un error al intentar escribir datos.
Si el error es « Error::IO », las escrituras posteriores en el documento subyacente QIODevice fallarán. En otros casos, es posible que se escriban datos malformados en el documento.
El estado de error nunca se restablece. Las operaciones de escritura que se produzcan tras el error pueden ignorarse, incluso si se ha solucionado la condición de error.
Véase también error(), errorString() y raiseError().
[since 6.10] void QXmlStreamWriter::raiseError(QAnyStringView message)
Genera un error personalizado con el objeto ` message` especificado.
Esta función sirve para indicar manualmente que se ha producido un error durante la escritura, como un fallo de validación a nivel de aplicación.
Esta función se introdujo en Qt 6.10.
Véanse también errorString(), error() y hasError().
void QXmlStreamWriter::setAutoFormatting(bool enable)
Activa el formato automático si enable es true; en caso contrario, lo desactiva.
El valor por defecto es false.
Nota: Funciónde configuración para la propiedad ` autoFormatting`.
Véase también autoFormatting().
void QXmlStreamWriter::setDevice(QIODevice *device)
Establece el dispositivo actual como device. Si deseas que el flujo escriba en un QByteArray, puedes crear un dispositivo QBuffer.
Véase también device().
void QXmlStreamWriter::writeAttribute(QAnyStringView namespaceUri, QAnyStringView name, QAnyStringView value)
Escribe un atributo con « name » y « value », precedido por el espacio de nombres especificado « namespaceUri ». Si el espacio de nombres aún no se ha declarado, « QXmlStreamWriter » generará una declaración de espacio de nombres para él.
Esta función solo se puede llamar después de writeStartElement() antes de escribir ningún contenido, o después de writeEmptyElement().
Nota: En las versiones de Qt anteriores a la 6.5, esta función aceptaba QString, y no QAnyStringView.
void QXmlStreamWriter::writeAttribute(const QXmlStreamAttribute &attribute)
Escribe el ` attribute`.
Esta función solo se puede llamar después de ` writeStartElement()` antes de escribir ningún contenido, o después de ` writeEmptyElement()`.
Se trata de una función sobrecargada.
void QXmlStreamWriter::writeAttribute(QAnyStringView qualifiedName, QAnyStringView value)
Escribe un atributo con qualifiedName y value.
Esta función solo se puede llamar después de writeStartElement() antes de escribir ningún contenido, o después de writeEmptyElement().
Nota: En las versiones de Qt anteriores a la 6.5, esta función aceptaba QString, no QAnyStringView.
Se trata de una función sobrecargada.
void QXmlStreamWriter::writeAttributes(const QXmlStreamAttributes &attributes)
Escribe el vector de atributos attributes. Si un espacio de nombres al que se hace referencia en un atributo aún no se ha declarado, QXmlStreamWriter generará una declaración de espacio de nombres para él.
Esta función solo se puede llamar después de writeStartElement() antes de escribir ningún contenido, o después de writeEmptyElement().
Véanse también writeAttribute() y writeNamespace().
void QXmlStreamWriter::writeCDATA(QAnyStringView text)
Escribe text como sección CDATA. Si text contiene la secuencia de caracteres prohibida «]]>», se divide en diferentes secciones CDATA.
Esta función existe principalmente para completar el conjunto de funciones. Normalmente no deberías necesitarla, ya que writeCharacters() escapa automáticamente todos los caracteres que no forman parte del contenido.
Nota: En las versiones de Qt anteriores a la 6.5, esta función aceptaba QString, no QAnyStringView.
void QXmlStreamWriter::writeCharacters(QAnyStringView text)
Escribe text. Los caracteres «<», «&» y «»» se escapan como referencias de entidad «<», «&» y «"». Para evitar la secuencia prohibida «]]>», el carácter «>» también se escapa como «>».
Nota: En las versiones de Qt anteriores a la 6.5, esta función aceptaba QString, no QAnyStringView.
Véase también writeEntityReference().
void QXmlStreamWriter::writeComment(QAnyStringView text)
Escribe text como comentario XML, donde text no debe contener la secuencia prohibida -- ni terminar en -. Ten en cuenta que XML no ofrece ninguna forma de escapar - en un comentario.
Nota: En las versiones de Qt anteriores a la 6.5, esta función aceptaba « QString », no « QAnyStringView ».
void QXmlStreamWriter::writeCurrentToken(const QXmlStreamReader &reader)
Escribe el estado actual de la función « reader ». Se admiten todos los estados válidos posibles.
El objetivo de esta función es facilitar el procesamiento en cadena de datos XML.
Véase también QXmlStreamReader::tokenType().
void QXmlStreamWriter::writeDTD(QAnyStringView dtd)
Escribe una sección DTD. El dtd representa la producción completa «doctypedecl» de la especificación XML 1.0.
Nota: En las versiones de Qt anteriores a la 6.5, esta función aceptaba ` QString`, y no ` QAnyStringView`.
void QXmlStreamWriter::writeDefaultNamespace(QAnyStringView namespaceUri)
Escribe una declaración de espacio de nombres predeterminado para namespaceUri.
Si se ha llamado a writeStartElement() o a writeEmptyElement(), la declaración se aplica al elemento actual; en caso contrario, se aplica al siguiente elemento hijo.
Ten en cuenta que los espacios de nombres http://www.w3.org/XML/1998/namespace (vinculado a xmlns) y http://www.w3.org/2000/xmlns/ (vinculado a xml) no pueden, por definición, declararse como predeterminados.
Nota: En las versiones de Qt anteriores a la 6.5, esta función aceptaba QString, en lugar de QAnyStringView.
void QXmlStreamWriter::writeEmptyElement(QAnyStringView namespaceUri, QAnyStringView name)
Escribe un elemento vacío con name, precedido por el espacio de nombres especificado namespaceUri. Si el espacio de nombres no se ha declarado, QXmlStreamWriter generará una declaración de espacio de nombres para él. Las llamadas posteriores a writeAttribute() añadirán atributos a este elemento.
Nota: En las versiones de Qt anteriores a la 6.5, esta función aceptaba QString, no QAnyStringView.
Véase también writeNamespace().
void QXmlStreamWriter::writeEmptyElement(QAnyStringView qualifiedName)
Escribe un elemento vacío con el nombre calificado qualifiedName. Las llamadas posteriores a writeAttribute() añadirán atributos a este elemento.
Nota: En las versiones de Qt anteriores a la 6.5, esta función aceptaba « QString », no « QAnyStringView ».
Se trata de una función sobrecargada.
void QXmlStreamWriter::writeEndDocument()
Cierra todos los elementos de inicio que queden abiertos y escribe un salto de línea.
Véase también writeStartDocument().
void QXmlStreamWriter::writeEndElement()
Cierra el elemento de inicio anterior.
Véase también writeStartElement().
void QXmlStreamWriter::writeEntityReference(QAnyStringView name)
Escribe la referencia de entidad name en el flujo, como «&name;».
Nota: En las versiones de Qt anteriores a la 6.5, esta función aceptaba QString, no QAnyStringView.
void QXmlStreamWriter::writeNamespace(QAnyStringView namespaceUri, QAnyStringView prefix = {})
Escribe una declaración de espacio de nombres para namespaceUri con prefix. Si prefix está vacío, QXmlStreamWriter asigna un prefijo único formado por la letra «n» seguida de un número.
Si se ha llamado a writeStartElement() o writeEmptyElement(), la declaración se aplica al elemento actual; en caso contrario, se aplica al siguiente elemento hijo.
Tenga en cuenta que el prefijo xml está predefinido y reservado para http://www.w3.org/XML/1998/namespace, que a su vez no puede vincularse a ningún otro prefijo. El prefijo xmlns y su URI http://www.w3.org/2000/xmlns/ se utilizan para el propio mecanismo de espacios de nombres y, por lo tanto, están totalmente prohibidos en las declaraciones.
Nota: En las versiones de Qt anteriores a la 6.5, esta función aceptaba « QString », y no « QAnyStringView ».
void QXmlStreamWriter::writeProcessingInstruction(QAnyStringView target, QAnyStringView data = {})
Escribe una instrucción de procesamiento XML con target y data, donde data no debe contener la secuencia «?>».
Nota: En las versiones de Qt anteriores a la 6.5, esta función aceptaba QString, no QAnyStringView.
void QXmlStreamWriter::writeStartDocument(QAnyStringView version)
Escribe un documento que comienza con el número de versión XML version.
Nota: Esta función no valida la cadena de versión y permite configurarla manualmente. Sin embargo, QXmlStreamWriter solo es compatible con XML 1.0. Establecer una cadena de versión distinta de «1.0» no modifica el comportamiento del escritor ni las reglas de escape. Es responsabilidad del usuario que llama a la función garantizar la coherencia entre la versión declarada y el contenido real.
Nota: En las versiones de Qt anteriores a la 6.5, esta función aceptaba QString, no QAnyStringView.
Véase también writeEndDocument().
void QXmlStreamWriter::writeStartDocument(QAnyStringView version, bool standalone)
Escribe un documento que comienza con el número de versión XML « version » y un atributo «standalone» « standalone ».
Nota: Esta función no valida la cadena de versión y permite configurarla manualmente. Sin embargo, QXmlStreamWriter solo admite XML 1.0. Establecer una cadena de versión distinta de «1.0» no modifica el comportamiento del escritor ni las reglas de escape. Es responsabilidad del usuario que llama a la función garantizar la coherencia entre la versión declarada y el contenido real.
Nota: En las versiones de Qt anteriores a la 6.5, esta función aceptaba QString, en lugar de QAnyStringView.
Véase también writeEndDocument().
void QXmlStreamWriter::writeStartDocument()
Escribe un documento que comienza con el número de versión XML «1.0».
Esta es una función sobrecargada.
Véase también writeEndDocument().
void QXmlStreamWriter::writeStartElement(QAnyStringView namespaceUri, QAnyStringView name)
Escribe un elemento inicial con name, precedido por el espacio de nombres especificado namespaceUri. Si el espacio de nombres aún no se ha declarado, QXmlStreamWriter generará una declaración de espacio de nombres para él. Las llamadas posteriores a writeAttribute() añadirán atributos a este elemento.
Nota: En las versiones de Qt anteriores a la 6.5, esta función aceptaba QString, no QAnyStringView.
Véase también writeNamespace(), writeEndElement() y writeEmptyElement().
void QXmlStreamWriter::writeStartElement(QAnyStringView qualifiedName)
Escribe un elemento inicial con qualifiedName. Las llamadas posteriores a writeAttribute() añadirán atributos a este elemento.
Nota: En las versiones de Qt anteriores a la 6.5, esta función aceptaba ` QString`, no ` QAnyStringView`.
Se trata de una función sobrecargada.
Véanse también writeEndElement() y writeEmptyElement().
void QXmlStreamWriter::writeTextElement(QAnyStringView namespaceUri, QAnyStringView name, QAnyStringView text)
Escribe un elemento de texto con el prefijo name, para el namespaceUri especificado y text. Si el espacio de nombres no se ha declarado, QXmlStreamWriter generará una declaración de espacio de nombres para él.
Esta es una función de conveniencia equivalente a:
stream.writeStartElement(namespaceUri, name);
stream.writeCharacters(text);
stream.writeEndElement();Nota: En las versiones de Qt anteriores a la 6.5, esta función aceptaba QString, no QAnyStringView.
void QXmlStreamWriter::writeTextElement(QAnyStringView qualifiedName, QAnyStringView text)
Escribe un elemento de texto con qualifiedName y text.
Esta es una función de conveniencia equivalente a:
stream.writeStartElement(qualifiedName);
stream.writeCharacters(text);
stream.writeEndElement();Nota: En las versiones de Qt anteriores a la 6.5, esta función aceptaba QString, no QAnyStringView.
Se trata de una función sobrecargada.
© 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.