PySide6.QtCore.QXmlStreamReader

class QXmlStreamReader

QXmlStreamReader 类提供了一个快速的解析器，用于通过简单的流式API读取格式良好的XML。更多…

概要

方法

注意

本文档可能包含从C++自动翻译到Python的代码片段。我们始终欢迎对代码片段翻译的贡献。如果您发现翻译问题，您也可以通过在我们的https:/bugreports.qt.io/projects/PYSIDE上创建工单来告知我们。

详细描述

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

QXmlStreamReader 提供了一个简单的流式API来解析格式良好的XML。它是首先将整个XML加载到DOM树（参见QDomDocument）的替代方案。QXmlStreamReader 从QIODevice（参见setDevice()）或原始QByteArray（参见addData()）读取数据。

Qt 提供了 QXmlStreamWriter 用于写入 XML。

流读取器的基本概念是将XML文档报告为一系列标记流，类似于SAX。QXmlStreamReader和SAX之间的主要区别在于这些XML标记是如何报告的。使用SAX时，应用程序必须提供处理程序（回调函数），这些处理程序在解析器方便时接收来自解析器的所谓XML事件。而使用QXmlStreamReader时，应用程序代码本身驱动循环，并在需要时逐个从读取器中拉取标记。这是通过调用readNext()来完成的，读取器从输入流中读取，直到完成下一个标记，此时返回tokenType()。然后可以使用一组方便的函数，包括isStartElement()和text()，来检查标记以获取有关已读取内容的信息。这种拉取方法的巨大优势在于可以构建递归下降解析器，这意味着你可以轻松地将XML解析代码拆分为不同的方法或类。这使得在解析XML时很容易跟踪应用程序自身的状态。

使用 QXmlStreamReader 的典型循环如下所示：

xml = QXmlStreamReader()
...
while not xml.atEnd():
      xml.readNext()
      ... // do processing

if xml.hasError():
      ... // do error handling

QXmlStreamReader 是一个格式良好的 XML 1.0 解析器，它不包含外部解析实体。只要没有发生错误，应用程序代码就可以放心，

  • 流读取器提供的数据满足W3C对格式良好的XML的标准，

  • 令牌以有效顺序提供。

除非 QXmlStreamReader 引发错误，否则它保证以下内容：

  • 所有标签都正确嵌套和关闭。

  • 内部实体的引用已被替换为正确的替换文本。

  • 属性已根据DTD的内部子集进行了规范化或添加。

  • 类型为StartDocument的令牌发生在所有其他令牌之前，除了注释和处理指令。

  • 最多只能有一个DOCTYPE元素（类型为DTD的标记）。

  • 如果存在，DOCTYPE 出现在所有其他元素之前，除了 StartDocument、注释和处理指令。

特别是，一旦看到任何类型的标记 StartElement、EndElement、Characters、EntityReference 或 EndDocument，就不会再看到类型为 StartDocument 或 DTD 的标记。如果输入流中存在此类标记且顺序错误，则会引发错误。

注意

令牌类型 Comment 和 ProcessingInstruction 可能出现在流中的任何位置。

如果在解析过程中发生错误，atEnd() 和 hasError() 返回 true，并且 error() 返回发生的错误。函数 errorString()、lineNumber()、columnNumber() 和 characterOffset() 用于构建适当的错误或警告消息。为了简化应用程序代码，QXmlStreamReader 包含一个 raiseError() 机制，允许您引发自定义错误，这些错误会触发相同的错误处理。

QXmlStream 书签示例 展示了如何使用递归下降技术通过流读取器读取 XML 书签文件（XBEL）。

命名空间

QXmlStream 理解并解析 XML 命名空间。例如，在 StartElement 的情况下，namespaceUri() 返回元素所在的命名空间，而 name() 返回元素的本地名称。namespaceUri 和名称的组合唯一标识一个元素。如果命名空间前缀未在读取器解析的 XML 实体中声明，则 namespaceUri 为空。

如果你解析的XML数据没有按照XML规范使用命名空间，或者根本没有使用命名空间，你可以使用元素的qualifiedName()来代替。限定名称是元素的prefix()后跟冒号，再跟元素的本地name()——就像元素在原始XML数据中出现的那样。由于namespaceUri到前缀的映射既不是唯一的也不是通用的，对于符合命名空间的XML数据，应避免使用qualifiedName()。

为了解析使用未声明命名空间前缀的独立文档，您可以使用namespaceProcessing属性完全关闭命名空间处理。

增量解析

QXmlStreamReader 是一个增量解析器。它可以处理文档无法一次性解析的情况，因为文档是以块的形式到达的（例如来自多个文件或通过网络连接）。当解析器在完整文档解析完毕之前耗尽数据时，它会报告一个 PrematureEndOfDocumentError。当更多数据到达时，无论是通过调用 addData() 还是因为网络 device() 提供了更多数据，解析器都会从 PrematureEndOfDocumentError 错误中恢复，并在下一次调用 readNext() 时继续解析新数据。

例如，如果您的应用程序使用网络访问管理器从网络读取数据，您将向管理器发出网络请求并接收网络回复作为响应。由于QNetworkReply是一个QIODevice，您将其readyRead()信号连接到一个自定义槽，例如在QNetworkAccessManager讨论中显示的代码片段中的slotReadyRead()。在此槽中，您使用readAll()读取所有可用数据，并使用addData()将其传递给XML流读取器。然后，您调用自定义的解析函数，该函数从读取器中读取XML事件。

性能和内存消耗

QXmlStreamReader 设计上是内存保守的，因为它不会将整个XML文档树存储在内存中，而是只存储当前报告的令牌。此外，QXmlStreamReader 避免了通常将XML文档映射到方便且符合Qt风格的API所需的许多小字符串分配。它通过将所有字符串数据报告为 QStringView 而不是实际的 QString 对象来实现这一点。在任何这些对象上调用 toString() 都会返回一个等效的实际 QString 对象。

class TokenType

此枚举指定了读取器刚刚读取的令牌类型。

常量

描述

QXmlStreamReader.NoToken

读取器尚未读取任何内容。

QXmlStreamReader.Invalid

发生了一个错误，已在 error() 和 errorString() 中报告。

QXmlStreamReader.StartDocument

读取器在documentVersion()中报告XML版本号，并在documentEncoding()中报告XML文档中指定的编码。如果文档声明为独立的，isStandaloneDocument()返回true；否则返回false。

QXmlStreamReader.EndDocument

读取器报告文档的结束。

QXmlStreamReader.StartElement

读取器报告元素的开始，使用namespaceUri()和name()。空元素也会报告为StartElement，紧接着是EndElement。可以调用便利函数readElementText()来连接所有内容，直到相应的EndElement。属性在attributes()中报告，命名空间声明在namespaceDeclarations()中报告。

QXmlStreamReader.EndElement

读取器报告元素的结束，使用 namespaceUri() 和 name() 。

QXmlStreamReader.Characters

读取器在text()中报告字符。如果字符全是空白，isWhitespace()返回true。如果字符来自CDATA部分，isCDATA()返回true。

QXmlStreamReader.Comment

读取器在text()中报告一个注释。

QXmlStreamReader.DTD

读取器在text()中报告DTD，在notationDeclarations()中报告符号声明，在entityDeclarations()中报告实体声明。DTD声明的详细信息在dtdName()、dtdPublicId()和dtdSystemId()中报告。

QXmlStreamReader.EntityReference

读取器报告了一个无法解析的实体引用。引用的名称在name()中报告，替换文本在text()中报告。

QXmlStreamReader.ProcessingInstruction

读取器在 processingInstructionTarget() 和 processingInstructionData() 中报告处理指令。
class ReadElementTextBehaviour

此枚举指定了readElementText()的不同行为。

常量

描述

QXmlStreamReader.ErrorOnUnexpectedElement

当遇到子元素时，引发一个UnexpectedElementError并返回到目前为止读取的内容。

QXmlStreamReader.IncludeChildElements

递归地包含子元素的文本。

QXmlStreamReader.SkipChildElements

跳过子元素。

在版本4.6中添加。

class Error

此枚举指定了不同的错误情况

常量

描述

QXmlStreamReader.NoError

没有发生错误。

QXmlStreamReader.CustomError

使用raiseError()引发了一个自定义错误

QXmlStreamReader.NotWellFormedError

解析器内部由于读取的XML格式不正确而引发错误。

QXmlStreamReader.PrematureEndOfDocumentError

输入流在解析格式良好的XML文档之前结束。如果流中有更多的XML数据到达，可以通过调用addData()或等待它到达device()来从此错误中恢复。

QXmlStreamReader.UnexpectedElementError

解析器遇到了一个与预期不同的元素或标记。
__init__()

构建一个流读取器。

另请参阅

setDevice() addData()

__init__(data)
Parameters:

data – 字符串

创建一个新的流读取器，从data读取数据。

注意

在Qt 6.5之前的版本中，此构造函数被重载为QString和const char*。

另请参阅

addData() clear() setDevice()

__init__(device)
Parameters:

设备 – QIODevice

创建一个新的流读取器，从device读取数据。

另请参阅

setDevice() clear()

addData(data)
Parameters:

data – 字符串

为读取器添加更多data以供读取。如果读取器有device()，此函数不执行任何操作。

注意

在Qt 6.5之前的版本中，此函数被重载用于QString和const char*。

另请参阅

readNext() clear()

addExtraNamespaceDeclaration(extraNamespaceDeclaraction)
Parameters:

extraNamespaceDeclaraction – QXmlStreamNamespaceDeclaration

添加一个extraNamespaceDeclaration。该声明将对当前元素的子元素有效，或者如果该函数在任何元素被读取之前调用，则对整个XML文档有效。

addExtraNamespaceDeclarations(extraNamespaceDeclaractions)
Parameters:

extraNamespaceDeclaractions – QXmlStreamNamespaceDeclaration 的列表

添加由extraNamespaceDeclarations指定的声明向量。

atEnd()
Return type:

布尔

如果读取器已经读取到XML文档的末尾，或者发生了error()并且读取被中止，则返回true。否则，返回false。

当atEnd()和hasError()返回true且error()返回PrematureEndOfDocumentError时，意味着到目前为止XML格式良好，但尚未解析完整的XML文档。如果XML是从QByteArray读取的，可以通过addData()添加下一块XML；如果XML是从QIODevice读取的，可以通过等待更多数据到达。无论哪种方式，一旦有更多数据可用，atEnd()将再次返回false。

attributes()
Return type:

QXmlStreamAttributes

返回StartElement的属性。

characterOffset()
Return type:

整数

返回当前字符偏移量，从0开始。

clear()

移除阅读器中的任何device()或数据，并将其内部状态重置为初始状态。

另请参阅

addData()

columnNumber()
Return type:

整数

返回当前列号，从0开始。

device()
Return type:

QIODevice

返回与QXmlStreamReader关联的当前设备，如果未分配设备，则返回None。

另请参阅

setDevice()

documentEncoding()
Return type:

字符串

如果tokenType()是StartDocument，此函数返回XML声明中指定的编码字符串。否则返回空字符串。

documentVersion()
Return type:

字符串

如果tokenType()是StartDocument，此函数返回XML声明中指定的版本字符串。否则返回空字符串。

dtdName()
Return type:

字符串

如果 tokenType() 是 DTD，此函数返回 DTD 的名称。否则返回空字符串。

dtdPublicId()
Return type:

字符串

如果tokenType()是DTD，此函数将返回DTD的公共标识符。否则返回空字符串。

dtdSystemId()
Return type:

字符串

如果 tokenType() 是 DTD，此函数返回 DTD 的系统标识符。否则返回空字符串。

entityDeclarations()
Return type:

QXmlStreamEntityDeclaration的列表

如果tokenType()是DTD，此函数返回DTD的未解析（外部）实体声明。否则返回一个空向量。

QXmlStreamEntityDeclarations 类被定义为 QXmlStreamEntityDeclaration 的 QList。

entityExpansionLimit()
Return type:

整数

返回单个实体允许扩展的最大字符数。如果单个实体扩展超过给定限制，文档将不被视为格式良好。

entityResolver()
Return type:

QXmlStreamEntityResolver

返回实体解析器，如果没有实体解析器则返回None。

另请参阅

setEntityResolver()

error()
Return type:

错误

返回当前错误的类型，如果没有发生错误，则返回NoError。

errorString()
Return type:

字符串

返回由raiseError()设置的错误信息。

hasError()
Return type:

布尔

如果发生错误，返回true，否则返回false。

另请参阅

errorString() error()

hasStandaloneDeclaration()
Return type:

布尔

如果此文档有明确的独立声明（可以是‘yes’或‘no’），则返回true；否则返回false；

如果没有解析到XML声明，此函数将返回false。

另请参阅

isStandaloneDocument()

isCDATA()
Return type:

布尔

如果读取器报告来自CDATA部分的字符，则返回true；否则返回false。

另请参阅

isCharacters() text()

isCharacters()
Return type:

布尔

如果tokenType()等于Characters，则返回true；否则返回false。

另请参阅

isWhitespace() isCDATA()

isComment()
Return type:

布尔

如果tokenType()等于Comment，则返回true；否则返回false。

isDTD()
Return type:

布尔

如果tokenType()等于DTD，则返回true；否则返回false。

isEndDocument()
Return type:

布尔

如果tokenType()等于EndDocument，则返回true；否则返回false。

isEndElement()
Return type:

布尔

如果tokenType()等于EndElement，则返回true；否则返回false。

isEntityReference()
Return type:

布尔

如果tokenType()等于EntityReference，则返回true；否则返回false。

isProcessingInstruction()
Return type:

布尔

如果tokenType()等于ProcessingInstruction，则返回true；否则返回false。

isStandaloneDocument()
Return type:

布尔

如果此文档在XML声明中已被声明为独立的，则返回true；否则返回false。

如果没有解析到XML声明，此函数将返回false。

isStartDocument()
Return type:

布尔

如果tokenType()等于StartDocument，则返回true；否则返回false。

isStartElement()
Return type:

布尔

如果tokenType()等于StartElement，则返回true；否则返回false。

isWhitespace()
Return type:

布尔

如果读取器报告仅由空白字符组成的字符，则返回true；否则返回false。

另请参阅

isCharacters() text()

lineNumber()
Return type:

整数

返回当前行号，从1开始。

name()
Return type:

字符串

返回StartElement、EndElement或EntityReference的本地名称。

namespaceDeclarations()
Return type:

QXmlStreamNamespaceDeclaration的列表

如果 tokenType() 是 StartElement，此函数返回元素的命名空间声明。否则返回一个空向量。

QXmlStreamNamespaceDeclarations 类被定义为 QXmlStreamNamespaceDeclaration 的 QList。

namespaceProcessing()
Return type:

布尔

另请参阅

setNamespaceProcessing()

namespaceUri()
Return type:

字符串

返回StartElement或EndElement的命名空间URI。

另请参阅

name() qualifiedName()

notationDeclarations()
Return type:

QXmlStreamNotationDeclaration的列表

如果 tokenType() 是 DTD，此函数返回 DTD 的符号声明。否则返回一个空向量。

QXmlStreamNotationDeclarations 类被定义为 QXmlStreamNotationDeclaration 的 QList。

prefix()
Return type:

字符串

返回StartElement或EndElement的前缀。

另请参阅

name() qualifiedName()

processingInstructionData()
Return type:

字符串

返回ProcessingInstruction的数据。

processingInstructionTarget()
Return type:

字符串

返回ProcessingInstruction的目标。

qualifiedName()
Return type:

字符串

返回StartElement或EndElement的限定名称；

限定名称是XML数据中元素的原始名称。它由命名空间前缀、冒号和元素的本地名称组成。由于命名空间前缀不是唯一的（相同的前缀可以指向不同的命名空间，不同的前缀可以指向相同的命名空间），您不应该使用qualifiedName()，而应该使用解析的namespaceUri()和属性的本地name()。

raiseError([message=""])
Parameters:

消息 – str

使用可选的错误message引发自定义错误。

另请参阅

error() errorString()

readElementText([behaviour=QXmlStreamReader.ReadElementTextBehaviour.ErrorOnUnexpectedElement])
Parameters:

行为 – ReadElementTextBehaviour

Return type:

字符串

方便函数，在读取到StartElement时调用。读取直到相应的EndElement并返回中间的所有文本。如果没有错误，调用此函数后的当前标记（参见tokenType()）是EndElement。

该函数在读取Characters或EntityReference标记时连接text()，但跳过ProcessingInstruction和Comment。如果当前标记不是StartElement，则返回空字符串。

behaviour 定义了在到达 EndElement 之前读取到其他内容时会发生什么。该函数可以包含来自子元素的文本（例如对 HTML 有用），忽略子元素，或者引发 UnexpectedElementError 并返回到目前为止读取的内容（默认）。

readNext()
Return type:

TokenType

读取下一个标记并返回其类型。

有一个例外，一旦error()被readNext()报告，进一步读取XML流将不再可能。然后atEnd()返回true，hasError()返回true，并且此函数返回Invalid。

例外情况是当error()返回PrematureEndOfDocumentError时。当到达一个格式良好的XML块的末尾，但该块不代表一个完整的XML文档时，会报告此错误。在这种情况下，可以通过调用addData()来添加下一个XML块来恢复解析，当从QByteArray读取流时，或者通过等待更多数据到达当从device()读取流时。

另请参阅

tokenType() tokenString()

readNextStartElement()
Return type:

布尔

读取直到当前元素内的下一个开始元素。当到达开始元素时返回true。当到达结束元素或发生错误时，返回false。

当前元素是与最近解析的开始元素匹配的元素，尚未到达匹配的结束元素。当解析器到达结束元素时，当前元素变为父元素。

这是一个方便的函数，适用于当你只关心解析XML元素时。QXmlStream Bookmarks Example广泛使用了这个函数。

另请参阅

readNext()

setDevice(device)
Parameters:

设备 – QIODevice

将当前设备设置为device。设置设备会将流重置为其初始状态。

另请参阅

device() clear()

setEntityExpansionLimit(limit)
Parameters:

limit – int

设置单个实体允许扩展的最大字符数为limit。如果单个实体扩展超过给定的限制，文档将被视为格式不正确。

设置限制是为了防止在加载未知的XML文档时发生DoS攻击，否则递归实体扩展可能会耗尽所有可用内存。

此属性的默认值为4096个字符。

另请参阅

entityExpansionLimit

setEntityResolver(resolver)
Parameters:

解析器 – QXmlStreamEntityResolver

使 resolver 成为新的 entityResolver() 。

流读取器不拥有解析器的所有权。调用者有责任确保解析器在流读取器对象的整个生命周期内有效，或者直到设置了另一个解析器或None。

另请参阅

entityResolver()

setNamespaceProcessing(arg__1)
Parameters:

arg__1 – 布尔值

另请参阅

namespaceProcessing()

skipCurrentElement()

读取直到当前元素的末尾，跳过任何子节点。此函数对于跳过未知元素非常有用。

当前元素是与最近解析的开始元素匹配的元素，尚未到达匹配的结束元素。当解析器到达结束元素时，当前元素变为父元素。

text()
Return type:

字符串

返回Characters、Comment、DTD或EntityReference的文本。

tokenString()
Return type:

字符串

返回读取器当前令牌作为字符串。

另请参阅

tokenType()

tokenType()
Return type:

TokenType

返回当前令牌的类型。

当前的标记也可以通过便捷函数 isStartDocument()、isEndDocument()、isStartElement()、isEndElement()、isCharacters()、isComment()、isDTD()、isEntityReference() 和 isProcessingInstruction() 进行查询。

另请参阅

tokenString()