QXmlStreamWriter Class
QXmlStreamWriter 类提供了一个具有简单流 API 的 XML 写入器。更多
| Header： | #include <QXmlStreamWriter> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS Core)target_link_libraries(mytarget PRIVATE Qt6::Core) |
| qmake： | QT += core |
- 所有成员（包括继承成员）的列表
- QXmlStreamWriter 属于XML 类。
注意：该类中的所有函数都是可重入的。
属性
- autoFormatting : bool
- autoFormattingIndent : int
公共功能
| QXmlStreamWriter() | |
| QXmlStreamWriter(QByteArray *array) | |
| QXmlStreamWriter(QIODevice *device) | |
| QXmlStreamWriter(QString *string) | |
| ~QXmlStreamWriter() | |
| bool | autoFormatting() const |
| int | autoFormattingIndent() const |
| QIODevice * | device() const |
| bool | hasError() const |
| void | setAutoFormatting(bool enable) |
| void | setAutoFormattingIndent(int spacesOrTabs) |
| void | setDevice(QIODevice *device) |
| 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。与相关类一样，它在QIODevice 上运行，该 由setDevice() 指定。API 简单明了：对于要写入的每个 XML 标记或事件，Writer 都会提供一个专门的函数。
您可以使用writeStartDocument() 开始文档，并使用writeEndDocument() 结束文档。这将隐式关闭所有剩余的打开标记。
元素标记用writeStartElement() 打开，然后是writeAttribute() 或writeAttributes()、元素内容，最后是writeEndElement()。更短的格式writeEmptyElement() 可用来编写空元素，然后是writeAttributes()。
元素内容由字符、实体引用或嵌套元素组成。它是用writeCharacters() 写成的，它还负责转义所有禁止使用的字符和字符序列、writeEntityReference() 或对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 始终以 UTF-8 编码 XML。
如果在写入底层设备时发生错误，hasError() 将开始返回 true，随后的写入将被忽略。
QXmlStream Bookmarks 示例说明了如何使用流写入器写入先前由QXmlStreamReader 读入的 XML 书签文件 (XBEL)。
属性文档
autoFormatting : bool
该属性是流写入器的自动格式化标志。
该属性控制流写入器是否自动格式化生成的 XML 数据。如果启用，写入器会自动为元素之间的空白部分（可忽略的空白）添加换行符和缩进。自动格式化的主要目的是将数据分成几行，增加人类读者的可读性。缩进深度可通过autoFormattingIndent 属性进行控制。
默认情况下，自动格式化是禁用的。
访问功能
| bool | autoFormatting() const |
| void | setAutoFormatting(bool enable) |
autoFormattingIndent : int
该属性用于保存启用自动格式化时缩进的空格或制表符数量。正数表示空格，负数表示制表符。
默认缩进为 4。
访问功能：
| int | autoFormattingIndent() const |
| void | setAutoFormattingIndent(int spacesOrTabs) |
另请参阅 autoFormatting 。
成员函数文档
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().
bool QXmlStreamWriter::hasError() const
如果写入失败，则返回true 。
如果数据流未能写入底层设备，或者要写入的数据包含无效字符，就会发生这种情况。
错误状态永远不会重置。即使清除了错误状态，错误发生后的写入也可能被忽略。
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)
为指定的namespaceUri 写入带有name 和value 前缀的属性。如果命名空间尚未声明，QXmlStreamWriter 将为其生成命名空间声明。
该函数只能在写入任何内容之前的writeStartElement() 之后或writeEmptyElement() 之后调用。
注意： 在 6.5 之前的 Qt 版本中，该函数使用的是QString ，而不是QAnyStringView 。
void QXmlStreamWriter::writeAttribute(const QXmlStreamAttribute &attribute)
这是一个重载函数。
写入attribute 。
该函数只能在写入任何内容之前的writeStartElement() 之后或writeEmptyElement() 之后调用。
void QXmlStreamWriter::writeAttribute(QAnyStringView qualifiedName, QAnyStringView value)
这是一个重载函数。
通过qualifiedName 和value 写入一个属性。
该函数只能在写入任何内容之前的writeStartElement() 之后或writeEmptyElement() 之后调用。
注意： 在 6.5 之前的 Qt XML 版本中，该函数使用QString ，而不是QAnyStringView 。
void QXmlStreamWriter::writeAttributes(const QXmlStreamAttributes &attributes)
写入属性向量attributes 。如果属性中引用的命名空间尚未声明，QXmlStreamWriter 将为其生成命名空间声明。
该函数只能在写入任何内容之前的writeStartElement() 或writeEmptyElement() 之后调用。
另请参见 writeAttribute() 和writeNamespace()。
void QXmlStreamWriter::writeCDATA(QAnyStringView text)
将text 写入 CDATA 部分。如果text 包含禁止字符序列"]]>"，则会被分割成不同的 CDATA 部分。
该函数主要是为了完整性而存在。通常情况下，您不需要使用它，因为writeCharacters() 会自动转义所有非内容字符。
注意： 在 6.5 之前的 Qt 版本中，该函数使用的是QString ，而不是QAnyStringView 。
void QXmlStreamWriter::writeCharacters(QAnyStringView text)
写入text 。字符"<"、"&"和""被转义为实体引用"<"、"&和"""。为避免出现禁止序列"]]>"，">"也转义为">"。
注意： 在 6.5 之前的 Qt 版本中，该函数使用QString ，而不是QAnyStringView 。
另请参阅 writeEntityReference() 。
void QXmlStreamWriter::writeComment(QAnyStringView text)
将text 写成 XML 注释，其中text 不得包含禁止序列-- 或以- 结尾。请注意，XML 不提供在注释中转义- 的任何方法。
注意： 在 6.5 之前的 Qt XML 版本中，该函数使用的是QString ，而不是QAnyStringView 。
void QXmlStreamWriter::writeCurrentToken(const QXmlStreamReader &reader)
写入reader 的当前状态。支持所有可能的有效状态。
该函数的目的是支持 XML 数据的链式处理。
另请参见 QXmlStreamReader::tokenType()。
void QXmlStreamWriter::writeDTD(QAnyStringView dtd)
写入 DTD 部分。dtd 代表 XML 1.0 规范中的整个 doctypedecl 制作。
注意： 在 6.5 之前的 Qt XML 版本中，该函数使用的是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）不能声明为默认值。
注意： 在 6.5 之前的 Qt 版本中，该函数使用QString ，而不是QAnyStringView 。
void QXmlStreamWriter::writeEmptyElement(QAnyStringView namespaceUri, QAnyStringView name)
为指定的namespaceUri 写入带有name 前缀的空元素。如果命名空间尚未声明，QXmlStreamWriter 将为其生成命名空间声明。随后对writeAttribute() 的调用将为该元素添加属性。
注意： 在 6.5 之前的 Qt 版本中，该函数使用QString ，而不是QAnyStringView 。
另请参阅 writeNamespace()。
void QXmlStreamWriter::writeEmptyElement(QAnyStringView qualifiedName)
这是一个重载函数。
它将写入一个空元素，其限定名称为qualifiedName 。随后对writeAttribute() 的调用将为该元素添加属性。
注意： 在 6.5 之前的 Qt 版本中，该函数使用QString ，而不是QAnyStringView 。
void QXmlStreamWriter::writeEndDocument()
关闭所有剩余的开放起始元素，并写入换行符。
另请参见 writeStartDocument().
void QXmlStreamWriter::writeEndElement()
关闭前一个起始元素。
另请参见 writeStartElement().
void QXmlStreamWriter::writeEntityReference(QAnyStringView name)
将实体引用name 写入数据流，格式为"&name;"。
注： 在 6.5 之前的 Qt 版本中，此函数使用QString ，而非QAnyStringView 。
void QXmlStreamWriter::writeNamespace(QAnyStringView namespaceUri, QAnyStringView prefix = {})
通过prefix 为namespaceUri 写命名空间声明。如果prefix 为空，则QXmlStreamWriter 会指定一个由字母 "n "和数字组成的唯一前缀。
如果调用了writeStartElement() 或writeEmptyElement() ，则声明适用于当前元素；否则适用于下一个子元素。
请注意，前缀xml既是预定义的，也是为http://www.w3.org/XML/1998/namespace 保留的，而http://www.w3.org/XML/1998/namespace 又不能与任何其他前缀绑定。前缀xmlns及其 URIhttp://www.w3.org/2000/xmlns/用于命名空间机制本身，因此在声明中完全禁止使用。
注意： 在 6.5 之前的 Qt 版本中，该函数使用的是QString ，而不是QAnyStringView 。
void QXmlStreamWriter::writeProcessingInstruction(QAnyStringView target, QAnyStringView data = {})
写入包含target 和data 的 XML 处理指令，其中data 不得包含序列"?>"。
注： 在 6.5 之前的 Qt XML 版本中，该函数使用QString ，而不是QAnyStringView 。
void QXmlStreamWriter::writeStartDocument(QAnyStringView version)
写入以 XML 版本号version 开始的文档。
注意： 在 6.5 之前的 Qt XML 版本中，该函数使用QString ，而不是QAnyStringView 。
另请参阅 writeEndDocument() 。
void QXmlStreamWriter::writeStartDocument(QAnyStringView version, bool standalone)
写入以 XML 版本号version 和独立属性standalone 开始的文档。
注： 在 6.5 之前的 Qt XML 版本中，该函数使用QString ，而非QAnyStringView 。
另请参阅 writeEndDocument() 。
void QXmlStreamWriter::writeStartDocument()
这是一个重载函数。
以 XML 版本号 "1.0 "开始写入文档。
另请参见 writeEndDocument().
void QXmlStreamWriter::writeStartElement(QAnyStringView namespaceUri, QAnyStringView name)
为指定的namespaceUri 写入以name 为前缀的起始元素。如果命名空间尚未声明，QXmlStreamWriter 将为其生成命名空间声明。随后对writeAttribute() 的调用将为该元素添加属性。
注意： 在 6.5 之前的 Qt 版本中，该函数使用的是QString ，而不是QAnyStringView 。
另请参阅 writeNamespace()、writeEndElement() 和writeEmptyElement()。
void QXmlStreamWriter::writeStartElement(QAnyStringView qualifiedName)
这是一个重载函数。
使用qualifiedName 写入一个起始元素。随后对writeAttribute() 的调用将为该元素添加属性。
注意： 在 6.5 之前的 Qt 版本中，此函数使用QString ，而不是QAnyStringView 。
另请参阅 writeEndElement() 和writeEmptyElement()。
void QXmlStreamWriter::writeTextElement(QAnyStringView namespaceUri, QAnyStringView name, QAnyStringView text)
写入带有name 的文本元素，前缀为指定的namespaceUri 和text 。如果命名空间尚未声明，QXmlStreamWriter 将为其生成命名空间声明。
这是一个方便的函数，相当于
writeStartElement(namespaceUri, name); writeCharacters(text); writeEndElement();
注意： 在 6.5 之前的 Qt 版本中，该函数使用QString ，而不是QAnyStringView 。
void QXmlStreamWriter::writeTextElement(QAnyStringView qualifiedName, QAnyStringView text)
这是一个重载函数。
使用qualifiedName 和text 写入文本元素。
这是一个方便的函数，相当于
writeStartElement(qualifiedName); writeCharacters(text); writeEndElement();
注： 在 6.5 之前的 Qt 版本中，此函数使用QString ，而非QAnyStringView 。
© 2025 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.
