QXmlStreamWriter Class
QXmlStreamWriter 类提供了一个具有简单流式 API 的 XML 1.0 写入器。更多内容...
| 头文件： | #include <QXmlStreamWriter> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS Core) target_link_libraries(mytarget PRIVATE Qt6::Core) |
| qmake： | QT += core |
- 所有成员的列表，包括继承的成员
- QXmlStreamWriter 属于XML 类。
注意：该类中的所有函数均为可重入的。
公共类型
(since 6.10) enum class | Error { None, IO, Encoding, InvalidCharacter, Custom } |
属性
- autoFormatting : bool
- autoFormattingIndent : int
(since 6.10)stopWritingOnError : bool
公共函数
| 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) |
详细说明
QXmlStreamWriter 是QXmlStreamReader 的对应类，用于写入 XML。它符合 XML 1.0 规范，并使用 XML 1.0 语法、转义规则和字符有效性约束来写入文档。
注意： 不支持XML 1.1。虽然可以在输出中手动设置版本字符串，但无法使用此类生成需要 XML 1.1 特定功能（例如额外控制字符）的文档。
与相关类一样，它基于通过 `setDevice()` 指定的 `QIODevice ` 进行操作。其 API 简单直观：对于您想要写入的每个 XML 标记或事件，该写入器都提供了一个专用函数。
您使用writeStartDocument() 开始文档，并使用writeEndDocument() 结束文档。这将隐式关闭所有剩余的未闭合标签。
元素标签的打开方式为：writeStartElement()，随后是writeAttribute()或writeAttributes()，接着是元素内容，最后以writeEndElement()结束。写入空元素时，可以使用简写形式writeEmptyElement()，随后调用writeAttributes()。
writeEntityReference元素内容可以由字符、实体引用或嵌套元素组成。其写入方式包括：writeCharacters()（该方法会自动对所有禁止的字符和字符序列进行转义）、 ()，或后续调用writeStartElement()。对于仅包含文本的终结元素，可以使用便捷方法writeTextElement()进行写入。
以下简化的代码片段展示了该类的基本用法，用于编写带缩进的格式化 XML：
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 会自动处理命名空间的前缀，您只需在写入元素或属性时指定namespaceUri 即可。如果必须遵循特定的前缀，您可以通过writeNamespace() 或writeDefaultNamespace() 手动声明命名空间，从而强制写入器使用这些前缀。 此外，您还可以绕过流写入器的命名空间支持，转而使用接受限定名称的重载方法。命名空间http://www.w3.org/XML/1998/namespace是隐式的，并映射到前缀xml。
流写入器可自动对生成的 XML 数据进行格式化，在元素之间的空白部分添加换行符和缩进，从而使 XML 数据更易于人类阅读，并便于大多数源代码管理系统进行处理。可通过autoFormatting 属性启用此功能，并通过autoFormattingIndent 属性进行自定义。
其他函数包括writeCDATA()、writeComment()、writeProcessingInstruction() 以及writeDTD()。通过writeCurrentToken() 支持 XML 流的链式调用。
QXmlStreamWriter 始终将 XML 编码为 UTF-8。
如果写入过程中发生错误，hasError() 将返回 true。但是，默认情况下，在发生错误时已缓冲的数据，或者在同一操作中写入的数据，仍可能会被写入底层设备。 这适用于Error::Encoding 、Error::InvalidCharacter 以及用户引发的Error::Custom 。若要避免这种情况并确保错误发生后不再写入任何数据，请使用stopWritingOnError 属性。启用此属性后，第一个错误会立即停止输出，写入器将忽略所有后续的写入操作。应用程序应将错误状态视为终止状态，并在发生错误后避免继续使用该写入器。
QXmlStream 书签示例演示了如何使用流写入器写入一个 XML 书签文件（XBEL），该文件此前已由QXmlStreamReader 读取。
成员类型文档
[since 6.10] enum class QXmlStreamWriter::Error
此枚举指定了使用QXmlStreamWriter 写入XML时可能出现的各种错误情况。
| 常量 | 值 | 描述 |
|---|---|---|
QXmlStreamWriter::Error::None | 0 | 未发生错误。 |
QXmlStreamWriter::Error::IO | 1 | 向设备写入时发生 I/O 错误。 |
QXmlStreamWriter::Error::Encoding | 2 | 在将字符转换为输出格式时发生了编码错误。 |
QXmlStreamWriter::Error::InvalidCharacter | 3 | 写入时遇到 XML 1.0 中不允许的字符。 |
QXmlStreamWriter::Error::Custom | 4 | 已通过 `raiseError()` 引发了一个自定义错误。 |
该枚举在 Qt 6.10 中引入。
属性文档
autoFormatting : bool
该属性保存流写入器的自动格式化标志。
该属性控制流写入器是否自动对生成的 XML 数据进行格式化。如果启用，写入器会自动在元素之间的空白区域（可忽略的空白字符）中添加换行符和缩进。 自动格式化的主要目的是将数据拆分为多行，从而提高人类读者的可读性。缩进深度可通过autoFormattingIndent 属性进行控制。
默认情况下，自动格式化处于禁用状态。
访问函数：
| bool | autoFormatting() const |
| void | setAutoFormatting(bool enable) |
autoFormattingIndent : int
当启用自动格式化时，此属性用于指定缩进所用的空格或制表符的数量。正数表示空格，负数表示制表符。
默认缩进值为 4。
访问函数：
| int | autoFormattingIndent() const |
| void | setAutoFormattingIndent(int spacesOrTabs) |
另请参阅 autoFormatting 。
[since 6.10] stopWritingOnError : bool
此属性用于控制在遇到错误后是否停止向设备写入数据。
如果将此属性设置为true ，写入器在遇到任何错误时会立即停止写入，并忽略所有后续的写入操作。当此属性设置为false 时，写入器在发生错误后可能会继续写入，跳过无效的写入操作，但允许后续输出。
请注意，这包括Error::InvalidCharacter 、Error::Encoding 和Error::Custom 。Error::IO 始终被视为终止错误，无论此设置如何，都会停止写入。
默认值为false 。
该枚举类型在 Qt 6.10 中引入。
访问函数：
| bool | stopWritingOnError() const |
| void | setStopWritingOnError(bool stop) |
成员函数文档
QXmlStreamWriter::QXmlStreamWriter()
创建一个流写入器。
另请参阅 setDevice()。
[explicit] QXmlStreamWriter::QXmlStreamWriter(QByteArray *array)
创建一个流写入器，用于向array 写入数据。这相当于创建一个在QBuffer 设备上运行的 XML 写入器，而该设备又运行在array 上。
[explicit] QXmlStreamWriter::QXmlStreamWriter(QIODevice *device)
创建一个流写入器，用于向device 写入数据；
[explicit] QXmlStreamWriter::QXmlStreamWriter(QString *string)
创建一个流写入器，用于向string 写入数据。
[noexcept] QXmlStreamWriter::~QXmlStreamWriter()
析构函数。
bool QXmlStreamWriter::autoFormatting() const
如果启用了自动格式化，则返回true ；否则返回false 。
注意： 这是 autoFormatting 属性的获取器函数 。
另请参阅 setAutoFormatting()。
QIODevice *QXmlStreamWriter::device() const
返回与QXmlStreamWriter 关联的当前设备；如果尚未分配设备，则返回nullptr 。
另请参阅 setDevice()。
[since 6.10] QXmlStreamWriter::Error QXmlStreamWriter::error() const
返回写入器的当前错误状态。
如果未发生错误，则该函数返回QXmlStreamWriter::Error::None 。
该函数于 Qt 6.10 版本中引入。
另请参阅 errorString()、raiseError() 和hasError()。
[since 6.10] QString QXmlStreamWriter::errorString() const
如果发生错误，则返回与其相关的错误消息。
该错误消息要么由QXmlStreamWriter 在内部设置，要么由用户通过raiseError()提供。如果未发生错误，则该函数返回空字符串。
该函数在 Qt 6.10 中引入。
另请参阅 error()、raiseError() 和hasError()。
bool QXmlStreamWriter::hasError() const
如果在尝试写入数据时发生错误，则返回true 。
如果错误代码为Error::IO ，后续对底层QIODevice 的写入操作将失败。在其他情况下，格式不正确的数据可能会被写入文档。
错误状态绝不会被重置。即使错误状态已被清除，在错误发生后进行的写入操作也可能被忽略。
另请参阅 error()、errorString() 和raiseError()。
[since 6.10] void QXmlStreamWriter::raiseError(QAnyStringView message)
根据给定的message 触发一个自定义错误。
此函数用于手动指示写入过程中发生错误，例如应用程序级别的验证失败。
该函数在 Qt 6.10 中引入。
另请参阅 errorString()、error() 和hasError()。
void QXmlStreamWriter::setAutoFormatting(bool enable)
如果enable 的值是true ，则启用自动格式化；否则禁用自动格式化。
默认值为false 。
注意： 这是属性autoFormatting 的设置 函数。
另请参阅 autoFormatting()。
void QXmlStreamWriter::setDevice(QIODevice *device)
将当前设备设置为device 。如果希望流写入QByteArray ，可以创建一个QBuffer 设备。
另请参阅 device()。
void QXmlStreamWriter::writeAttribute(QAnyStringView namespaceUri, QAnyStringView name, QAnyStringView value)
使用name 和value 写入属性，并在属性名前添加指定的namespaceUri 。如果尚未声明该命名空间，QXmlStreamWriter 将为其生成命名空间声明。
该函数只能在writeStartElement()之后、任何内容写入之前，或者在writeEmptyElement()之后调用。
注意：在 Qt 6.5 之前的版本中，此函数接受的是QString ，而不是QAnyStringView 。
void QXmlStreamWriter::writeAttribute(const QXmlStreamAttribute &attribute)
写入attribute 。
该函数只能在调用writeStartElement()之后、写入任何内容之前，或者在调用writeEmptyElement()之后调用。
这是一个重载函数。
void QXmlStreamWriter::writeAttribute(QAnyStringView qualifiedName, QAnyStringView value)
使用qualifiedName 和value 写入属性。
该函数只能在调用writeStartElement() 之后（在写入任何内容之前），或者在调用writeEmptyElement() 之后调用。
注意：在 Qt 6.5 之前的版本中，此函数接受QString ，而不是QAnyStringView 。
这是一个重载函数。
void QXmlStreamWriter::writeAttributes(const QXmlStreamAttributes &attributes)
写入属性向量attributes 。如果属性中引用的命名空间尚未声明，QXmlStreamWriter 将为其生成命名空间声明。
该函数只能在调用writeStartElement() 之后、在写入任何内容之前，或者在调用writeEmptyElement() 之后调用。
另请参阅 writeAttribute() 和writeNamespace()。
void QXmlStreamWriter::writeCDATA(QAnyStringView text)
将text 作为CDATA段写入。如果text 包含被禁止的字符序列"]]>"，则将其拆分为多个CDATA段。
此函数主要出于功能完整性的考虑而存在。通常您无需使用它，因为writeCharacters() 会自动对所有非内容字符进行转义。
注意：在 Qt 6.5 之前的版本中，此函数接受的是QString ，而不是QAnyStringView 。
void QXmlStreamWriter::writeCharacters(QAnyStringView text)
写入text 。字符“<”、“&”和“””会被转义为实体引用“<”、“&”和“"”。为避免出现禁止序列“]]>”，字符“>”也会被转义为“>”。
注意：在 Qt 6.5 之前的版本中，此函数接受QString 作为参数，而非QAnyStringView 。
另请参阅 writeEntityReference()。
void QXmlStreamWriter::writeComment(QAnyStringView text)
将text 作为 XML 注释写入，其中text 不得包含禁止序列-- ，也不得以- 结尾。请注意，XML 并未提供任何方法在注释中转义- 。
注意：在 Qt 6.5 之前的版本中，该函数接受的是QString ，而不是QAnyStringView 。
void QXmlStreamWriter::writeCurrentToken(const QXmlStreamReader &reader)
写入reader 的当前状态。支持所有可能的有效状态。
此函数的目的是支持 XML 数据的链式处理。
另请参阅 QXmlStreamReader::tokenType()。
void QXmlStreamWriter::writeDTD(QAnyStringView dtd)
写入一个 DTD 部分。dtd 代表 XML 1.0 规范中的整个 doctypedecl 生成规则。
注意：在 Qt 6.5 之前的版本中，此函数接受的是 `QString`，而不是 `QAnyStringView`。
void QXmlStreamWriter::writeDefaultNamespace(QAnyStringView namespaceUri)
为namespaceUri 编写默认命名空间声明。
如果调用了writeStartElement()或writeEmptyElement()，则该声明适用于当前元素；否则，它适用于下一个子元素。
请注意，根据定义，命名空间http://www.w3.org/XML/1998/namespace（绑定到xmlns）和http://www.w3.org/2000/xmlns/（绑定到xml）不能被声明为默认命名空间。
注意：在 Qt 6.5 之前的版本中，此函数的参数为QString ，而非QAnyStringView 。
void QXmlStreamWriter::writeEmptyElement(QAnyStringView namespaceUri, QAnyStringView name)
使用name 写入一个空元素，并在其名前添加指定的namespaceUri 。如果该命名空间尚未声明，QXmlStreamWriter 将为其生成命名空间声明。后续对writeAttribute()的调用将向该元素添加属性。
注意：在 Qt 6.5 之前的版本中，此函数接受QString ，而非QAnyStringView 。
另请参阅 writeNamespace()。
void QXmlStreamWriter::writeEmptyElement(QAnyStringView qualifiedName)
创建一个名称为qualifiedName 的空元素。后续对writeAttribute()的调用将向该元素添加属性。
注意：在 Qt 6.5 之前的版本中，此函数接受的是QString ，而不是QAnyStringView 。
这是一个重载函数。
void QXmlStreamWriter::writeEndDocument()
关闭所有剩余的未闭合起始标签，并写入一个换行符。
另请参阅 writeStartDocument()。
void QXmlStreamWriter::writeEndElement()
关闭上一个起始元素。
另请参阅 writeStartElement()。
void QXmlStreamWriter::writeEntityReference(QAnyStringView name)
将实体引用name 以“&name;”的形式写入流中。
注意：在 Qt 6.5 之前的版本中，此函数接受的是QString ，而不是QAnyStringView 。
void QXmlStreamWriter::writeNamespace(QAnyStringView namespaceUri, QAnyStringView prefix = {})
使用prefix 为namespaceUri 编写命名空间声明。如果prefix 为空，则QXmlStreamWriter 会分配一个由字母“n”后跟一个数字组成的唯一前缀。
如果调用了writeStartElement() 或writeEmptyElement()，则该声明适用于当前元素；否则，它适用于下一个子元素。
请注意，前缀xml既是预定义的，也是为http://www.w3.org/XML/1998/namespace 保留的，因此不能绑定到任何其他前缀。 前缀xmlns及其 URIhttp://www.w3.org/2000/xmlns/用于命名空间机制本身，因此完全禁止在声明中使用。
注意：在 Qt 6.5 之前的版本中，此函数接受的是 `QString`，而不是 `QAnyStringView`。
void QXmlStreamWriter::writeProcessingInstruction(QAnyStringView target, QAnyStringView data = {})
写入一个包含target 和data 的 XML 处理指令，其中data 不得包含字符串 "?>"。
注意：在 Qt 6.5 之前的版本中，此函数接受的是QString ，而不是QAnyStringView 。
void QXmlStreamWriter::writeStartDocument(QAnyStringView version)
创建一个以 XML 版本号version 开头的文档。
注意：此 函数不会对版本字符串进行验证，并允许手动设置该字符串。但是，QXmlStreamWriter 仅支持 XML 1.0。设置“1.0”以外的版本字符串不会改变写入器的行为或转义规则。确保声明的版本与实际内容之间的一致性是调用者的责任。
注意：在 Qt 6.5 之前的版本中，此函数接受QString 作为参数，而非QAnyStringView 。
另请参阅 writeEndDocument()。
void QXmlStreamWriter::writeStartDocument(QAnyStringView version, bool standalone)
创建一个文档，文档开头包含XML版本号version 以及standalone属性standalone 。
注意：此 函数不会对版本字符串进行有效性检查，并允许手动设置。但是，QXmlStreamWriter 仅支持 XML 1.0。设置“1.0”以外的版本字符串不会改变写入器的行为或转义规则。确保声明的版本与实际内容之间的一致性是调用者的责任。
注意：在 Qt 6.5 之前的版本中，此函数接受的是QString ，而非QAnyStringView 。
另请参阅 writeEndDocument()。
void QXmlStreamWriter::writeStartDocument()
写入一个以XML版本号“1.0”开头的文档。
这是一个重载函数。
另请参阅 writeEndDocument()。
void QXmlStreamWriter::writeStartElement(QAnyStringView namespaceUri, QAnyStringView name)
使用name 写入一个起始元素，并在其名前添加指定的namespaceUri 。如果该命名空间尚未声明，QXmlStreamWriter 将为其生成命名空间声明。后续对writeAttribute()的调用将向该元素添加属性。
注意：在 Qt 6.5 之前的版本中，该函数接受的是QString ，而非QAnyStringView 。
另请参阅 writeNamespace()、writeEndElement() 和writeEmptyElement()。
void QXmlStreamWriter::writeStartElement(QAnyStringView qualifiedName)
使用qualifiedName 写入一个起始元素。后续对writeAttribute()的调用将向该元素添加属性。
注意：在 Qt 6.5 之前的版本中，该函数接受的是QString ，而不是QAnyStringView 。
这是一个重载函数。
另请参见 writeEndElement() 和writeEmptyElement()。
void QXmlStreamWriter::writeTextElement(QAnyStringView namespaceUri, QAnyStringView name, QAnyStringView text)
使用name 写入文本元素，并为该元素添加指定namespaceUri 的前缀，同时设置text 。如果尚未声明该命名空间，QXmlStreamWriter 将为其生成命名空间声明。
这是一个等效于以下代码的便捷函数：
stream.writeStartElement(namespaceUri, name);
stream.writeCharacters(text);
stream.writeEndElement();注意：在 Qt 6.5 之前的版本中，此函数接受的是QString ，而不是QAnyStringView 。
void QXmlStreamWriter::writeTextElement(QAnyStringView qualifiedName, QAnyStringView text)
使用qualifiedName 和text 写入文本元素。
这是一个便捷函数，等同于：
stream.writeStartElement(qualifiedName);
stream.writeCharacters(text);
stream.writeEndElement();注意：在 Qt 6.5 之前的版本中，此函数接受的是 `QString`，而不是 `QAnyStringView`。
这是一个重载函数。
© 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.
