QXmlStreamWriter 类

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

头文件	#include <QXmlStreamWriter>
CMake	find_package(Qt6 REQUIRED COMPONENTS Core) target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake	QT += core

所有成员的列表，包括继承的成员
QXmlStreamWriter 是 XML 类的一部分。XML 类.

注意：此类中所有函数都是可重入的。

属性

autoFormatting : bool
autoFormattingIndent : int

公共函数

	QXmlStreamWriter()
	QXmlStreamWriter(QIODevice *device)
	QXmlStreamWriter(QByteArray *array)
	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(QAnyStringView qualifiedName, QAnyStringView value)
void	writeAttribute(const QXmlStreamAttribute &attribute)
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()
void	writeStartDocument(QAnyStringView version, bool standalone)
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 是用于写入 XML 的 QXmlStreamReader 的对应物。与相关类类似，它操作使用 setDevice() 指定的 QIODevice。API 简洁直观：为每个要写入的 XML 标记或事件，编写器提供了一个专门的函数。

你可以使用 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 书签示例说明了如何使用流编写器来写入之前由 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().

`[显式构造函数]` QXmlStreamWriter::QXmlStreamWriter(QIODevice **device*)

构建一个写入到 device 的流写入器；

`[显式构造函数]` QXmlStreamWriter::QXmlStreamWriter(QByteArray **array*)

构建一个写入到 array 的流写入器。这相当于创建一个操作 QBuffer 设备的 XML 写入器，该设备又操作 array。

`[显式构造函数]` QXmlStreamWriter::QXmlStreamWriter(QString **string*)

构建一个写入到 string 的流写入器。

`[非异常抛出构造函数]` QXmlStreamWriter::~QXmlStreamWriter()

析构函数。

bool QXmlStreamWriter::autoFormatting() const

如果启用自动格式化返回 true，否则返回 false。

注意： autoFormatting 属性的 getter 函数。

另请参阅 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)

写入具有 name 和 value 的属性，并在指定 namespaceUri 下进行前缀。如果命名空间尚未声明，QXmlStreamWriter 将为它生成一个命名空间声明。

此函数只能在调用 writeStartElement() 之后（在任何内容写入之前），或者调用 writeEmptyElement() 之后调用。

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

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

这是一个重载函数。

写入具有 qualifiedName 和 value 的属性。

此函数只能在调用 writeStartElement() 之后（在任何内容写入之前），或者调用 writeEmptyElement() 之后调用。

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

void QXmlStreamWriter::writeAttribute(const QXmlStreamAttribute &attribute)

这是一个重载函数。

写入 attribute。

此函数只能在调用 writeStartElement() 之后（在任何内容写入之前），或者调用 writeEmptyElement() 之后调用。

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)

将文本作为 XML 注释写入，其中文本必须不包含禁止的序列 -- 或以 - 结尾。请注意，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)

写入带有名称的空元素，该名称带有指定的 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)

将实体引用名称写入流，格式为 "&名称;"。

注意：在 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 及其 URI http://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 的文档开始。

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

另请参阅 writeEndDocument。

void QXmlStreamWriter::writeStartDocument()

这是一个重载函数。

使用 XML 版本号 "1.0" 写入文档开始。

另请参阅 writeEndDocument。

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

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

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

另请参阅 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 将为其生成命名空间声明。

这是一个方便的函数，相当于

        writeStartElement(namespaceUri, name);
        writeCharacters(text);
        writeEndElement();

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

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

这是一个重载函数。

写入具有 qualifiedName 和 text 的文本元素。

这是一个方便的函数，相当于

        writeStartElement(qualifiedName);
        writeCharacters(text);
        writeEndElement();

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

QXmlStreamWriter 类

属性

公共函数

详细描述

属性文档

autoFormatting : bool

autoFormattingIndent : int

成员函数文档

QXmlStreamWriter::QXmlStreamWriter()

[显式构造函数] QXmlStreamWriter::QXmlStreamWriter(QIODevice *device)

[显式构造函数] QXmlStreamWriter::QXmlStreamWriter(QByteArray *array)

[显式构造函数] QXmlStreamWriter::QXmlStreamWriter(QString *string)

[非异常抛出构造函数] QXmlStreamWriter::~QXmlStreamWriter()

bool QXmlStreamWriter::autoFormatting() const

QIODevice *QXmlStreamWriter::device() const

bool QXmlStreamWriter::hasError() const

void QXmlStreamWriter::setAutoFormatting(bool enable)

void QXmlStreamWriter::setDevice(QIODevice *device)

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

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

void QXmlStreamWriter::writeAttribute(const QXmlStreamAttribute &attribute)

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()

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

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)

`[显式构造函数]` QXmlStreamWriter::QXmlStreamWriter(QIODevice **device*)

`[显式构造函数]` QXmlStreamWriter::QXmlStreamWriter(QByteArray **array*)

`[显式构造函数]` QXmlStreamWriter::QXmlStreamWriter(QString **string*)

`[非异常抛出构造函数]` QXmlStreamWriter::~QXmlStreamWriter()

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