QXmlStreamWriter Class

QXmlStreamWriter 类提供了一个具有简单流 API 的 XML 1.0 写入器。更多

Header：	`#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 特定功能（如附加控制字符）的文档。

与相关类一样，该类也在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。不过，默认情况下，错误发生时已缓冲的数据或在同一操作中写入的数据仍可写入底层设备。这适用于Error::Encoding 、Error::InvalidCharacter 和用户引发的Error::Custom 。为避免这种情况并确保在错误发生后不写入数据，可使用stopWritingOnError 属性。启用该属性后，第一次出错会立即停止输出，写入器会忽略所有后续写入操作。应用程序应将错误状态视为终端，并避免在出错后继续使用写入器。

QXmlStream Bookmarks 示例说明了如何使用流写入器写入先前由QXmlStreamReader 读入的 XML 书签文件 (XBEL)。

成员类型文档

`[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(const QString &message) 和hasError()。

`[since 6.10]` QString QXmlStreamWriter::errorString() const

如果发生错误，则返回相关的错误信息。

错误信息由QXmlStreamWriter 内部设置，或由用户通过raiseError() 提供。如果未发生错误，该函数将返回一个空字符串。

此函数在 Qt 6.10 中引入。

另请参阅 error()、raiseError(const QString &message) 和hasError()。

bool QXmlStreamWriter::hasError() const

如果在尝试写入数据时发生错误，则返回true 。

如果错误是Error::IO ，则向底层QIODevice 的后续写入将失败。在其他情况下，可能会向文档写入畸形数据。

错误状态永远不会重置。即使错误状态被清除，错误发生后的写入也可能被忽略。

另请参阅 error(),errorString(), 以及 raiseError(const QString &message).

`[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)

为指定的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 版本中，此函数使用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 开始的文档。

注：该函数不验证版本字符串，允许手动设置。不过，QXmlStreamWriter 只支持 XML 1.0。设置 "1.0 "以外的版本字符串不会改变写入器的行为或转义规则。调用者有责任确保声明的版本与实际内容保持一致。

注意： 在 6.5 之前的 Qt 版本中，该函数使用QString ，而不是QAnyStringView 。

另请参阅 writeEndDocument() 。

void QXmlStreamWriter::writeStartDocument(QAnyStringView version, bool standalone)

写入带有 XML 版本号version 和独立属性standalone 的文档开头。

注意： 该函数不验证版本字符串，允许手动设置。但是，QXmlStreamWriter 只支持 XML 1.0。设置 "1.0 "以外的版本字符串不会改变写入器的行为或转义规则。调用者有责任确保声明的版本与实际内容保持一致。

注意： 在 6.5 之前的 Qt 版本中，该函数使用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.

QXmlStreamWriter Class

公共类型

属性

公共功能

详细说明

成员类型文档

[since 6.10] enum class QXmlStreamWriter::Error

属性文档

autoFormatting : bool

autoFormattingIndent : int

[since 6.10] stopWritingOnError : bool

成员函数文档

QXmlStreamWriter::QXmlStreamWriter()

[explicit] QXmlStreamWriter::QXmlStreamWriter(QByteArray *array)

[explicit] QXmlStreamWriter::QXmlStreamWriter(QIODevice *device)

[explicit] QXmlStreamWriter::QXmlStreamWriter(QString *string)

[noexcept] QXmlStreamWriter::~QXmlStreamWriter()

bool QXmlStreamWriter::autoFormatting() const

QIODevice *QXmlStreamWriter::device() const

[since 6.10] QXmlStreamWriter::Error QXmlStreamWriter::error() const

[since 6.10] QString QXmlStreamWriter::errorString() const

bool QXmlStreamWriter::hasError() const

[since 6.10] void QXmlStreamWriter::raiseError(QAnyStringView message)

void QXmlStreamWriter::setAutoFormatting(bool enable)

void QXmlStreamWriter::setDevice(QIODevice *device)

void QXmlStreamWriter::writeAttribute(QAnyStringView namespaceUri, QAnyStringView name, QAnyStringView value)

void QXmlStreamWriter::writeAttribute(const QXmlStreamAttribute &attribute)

void QXmlStreamWriter::writeAttribute(QAnyStringView qualifiedName, QAnyStringView value)

void QXmlStreamWriter::writeAttributes(const QXmlStreamAttributes &attributes)

void QXmlStreamWriter::writeCDATA(QAnyStringView text)

void QXmlStreamWriter::writeCharacters(QAnyStringView text)

void QXmlStreamWriter::writeComment(QAnyStringView text)

void QXmlStreamWriter::writeCurrentToken(const QXmlStreamReader &reader)

void QXmlStreamWriter::writeDTD(QAnyStringView dtd)

void QXmlStreamWriter::writeDefaultNamespace(QAnyStringView namespaceUri)

void QXmlStreamWriter::writeEmptyElement(QAnyStringView namespaceUri, QAnyStringView name)

void QXmlStreamWriter::writeEmptyElement(QAnyStringView qualifiedName)

void QXmlStreamWriter::writeEndDocument()

void QXmlStreamWriter::writeEndElement()

void QXmlStreamWriter::writeEntityReference(QAnyStringView name)

void QXmlStreamWriter::writeNamespace(QAnyStringView namespaceUri, QAnyStringView prefix = {})

void QXmlStreamWriter::writeProcessingInstruction(QAnyStringView target, QAnyStringView data = {})

void QXmlStreamWriter::writeStartDocument(QAnyStringView version)

void QXmlStreamWriter::writeStartDocument(QAnyStringView version, bool standalone)

void QXmlStreamWriter::writeStartDocument()

void QXmlStreamWriter::writeStartElement(QAnyStringView namespaceUri, QAnyStringView name)

void QXmlStreamWriter::writeStartElement(QAnyStringView qualifiedName)

void QXmlStreamWriter::writeTextElement(QAnyStringView namespaceUri, QAnyStringView name, QAnyStringView text)

void QXmlStreamWriter::writeTextElement(QAnyStringView qualifiedName, QAnyStringView text)

`[since 6.10]` enum class QXmlStreamWriter::Error

`[since 6.10]` stopWritingOnError : bool

`[explicit]` QXmlStreamWriter::QXmlStreamWriter(QByteArray **array*)

`[explicit]` QXmlStreamWriter::QXmlStreamWriter(QIODevice **device*)

`[explicit]` QXmlStreamWriter::QXmlStreamWriter(QString **string*)

`[noexcept]` QXmlStreamWriter::~QXmlStreamWriter()

`[since 6.10]` QXmlStreamWriter::Error QXmlStreamWriter::error() const

`[since 6.10]` QString QXmlStreamWriter::errorString() const

`[since 6.10]` void QXmlStreamWriter::raiseError(QAnyStringView message)

void QXmlStreamWriter::setDevice(QIODevice **device*)