QXmlStreamReader Class

QXmlStreamReader xml;
//...
while (!xml.atEnd()) {
    xml.readNext();
    //... do processing
}
if (xml.hasError()) {
    //... do error handling
}

成员函数文档

QXmlStreamReader::QXmlStreamReader()

构建一个流读取器。

另请参阅 setDevice() 和addData()。

[explicit] QXmlStreamReader::QXmlStreamReader(QAnyStringView data)

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

另请参阅 addData()、clear() 和setDevice()。

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

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

另请参阅 setDevice() 和clear()。

[explicit] QXmlStreamReader::QXmlStreamReader(const QByteArray &data)

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

另请参阅 addData()、clear() 和setDevice()。

[noexcept] QXmlStreamReader::~QXmlStreamReader()

摧毁了读者。

void QXmlStreamReader::addData(QAnyStringView data)

为阅读器添加更多data 内容供其读取。如果阅读器已调用device()，则此函数不执行任何操作。

另请参阅 readNext() 和clear()。

void QXmlStreamReader::addData(const QByteArray &data)

为阅读器添加更多data 供其读取。如果阅读器已调用device()，则此函数不执行任何操作。

另请参阅 readNext() 和clear()。

void QXmlStreamReader::addExtraNamespaceDeclaration(const QXmlStreamNamespaceDeclaration &extraNamespaceDeclaration)

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

另请参阅 namespaceDeclarations()、addExtraNamespaceDeclarations() 和setNamespaceProcessing()。

void QXmlStreamReader::addExtraNamespaceDeclarations(const QXmlStreamNamespaceDeclarations &extraNamespaceDeclarations)

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

另请参阅 namespaceDeclarations() 和addExtraNamespaceDeclaration()。

bool QXmlStreamReader::atEnd() const

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

当 atEnd() 和hasError() 返回 true，且error() 返回PrematureEndOfDocumentError 时，表示到目前为止 XML 格式正确，但尚未解析出完整的 XML 文档。 如果 XML 数据是从QByteArray 读取的，则可使用addData() 添加下一段 XML；如果 XML 数据是从QIODevice 读取的，则需等待更多数据到达。无论哪种情况，一旦有更多数据可用，atEnd() 都会返回 false。

另请参阅 hasError()、error()、device() 以及QIODevice::atEnd()。

QXmlStreamAttributes QXmlStreamReader::attributes() const

返回StartElement 的属性。

qint64 QXmlStreamReader::characterOffset() const

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

另请参见 lineNumber() 和columnNumber()。

void QXmlStreamReader::clear()

从读取器中移除所有device()或数据，并将读取器的内部状态重置为初始状态。

另请参阅 addData()。

qint64 QXmlStreamReader::columnNumber() const

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

另请参阅 lineNumber() 和characterOffset()。

QIODevice *QXmlStreamReader::device() const

返回与QXmlStreamReader 关联的当前设备；如果尚未分配任何设备，则返回nullptr 。

另请参阅 setDevice()。

QStringView QXmlStreamReader::documentEncoding() const

如果 `tokenType()` 的值为 `StartDocument`，则该函数返回 XML 声明中指定的编码字符串。否则，返回一个空字符串。

QStringView QXmlStreamReader::documentVersion() const

如果 `tokenType()` 的值为 `StartDocument`，则该函数返回 XML 声明中指定的版本字符串。否则，返回一个空字符串。

QStringView QXmlStreamReader::dtdName() const

如果 `tokenType()` 的值为 `DTD`，则该函数返回 DTD 的名称。否则，返回一个空字符串。

QStringView QXmlStreamReader::dtdPublicId() const

如果 `tokenType()` 的值为 `DTD`，则该函数返回 DTD 的公共标识符。否则，返回一个空字符串。

QStringView QXmlStreamReader::dtdSystemId() const

如果 `tokenType()` 的值为 `DTD`，则该函数返回 DTD 的系统标识符。否则，返回空字符串。

QXmlStreamEntityDeclarations QXmlStreamReader::entityDeclarations() const

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

QXmlStreamEntityDeclarations 类被定义为QXmlStreamEntityDeclaration 的QList 。

int QXmlStreamReader::entityExpansionLimit() const

返回单个实体允许展开的最大字符数。如果单个实体的展开长度超过了给定的限制，则该文档将被视为格式不正确。

另请参阅 setEntityExpansionLimit 。

QXmlStreamEntityResolver *QXmlStreamReader::entityResolver() const

返回实体解析器；如果不存在实体解析器，则返回nullptr 。

另请参阅 setEntityResolver()。

QXmlStreamReader::Error QXmlStreamReader::error() const

返回当前错误的类型；若未发生错误，则返回NoError 。

另请参阅 errorString() 和raiseError()。

QString QXmlStreamReader::errorString() const

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

另请参阅 error()、lineNumber()、columnNumber() 以及characterOffset()。

bool QXmlStreamReader::hasError() const

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

另请参阅 errorString() 和error()。

[since 6.6] bool QXmlStreamReader::hasStandaloneDeclaration() const

如果该文档包含显式的独立文档声明（可以是“yes”或“no”），则返回true ；否则返回false ；

如果未解析任何 XML 声明，则该函数返回false 。

该函数在 Qt 6.6 中引入。

另请参阅 isStandaloneDocument()。

bool QXmlStreamReader::isCDATA() const

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

另请参阅 isCharacters() 和text()。

bool QXmlStreamReader::isCharacters() const

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

另请参阅 isWhitespace() 和isCDATA()。

bool QXmlStreamReader::isComment() const

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

bool QXmlStreamReader::isDTD() const

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

bool QXmlStreamReader::isEndDocument() const

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

bool QXmlStreamReader::isEndElement() const

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

bool QXmlStreamReader::isEntityReference() const

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

bool QXmlStreamReader::isProcessingInstruction() const

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

bool QXmlStreamReader::isStandaloneDocument() const

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

如果未解析任何 XML 声明，则该函数返回 `false`。

另请参阅 hasStandaloneDeclaration()。

bool QXmlStreamReader::isStartDocument() const

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

bool QXmlStreamReader::isStartElement() const

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

bool QXmlStreamReader::isWhitespace() const

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

另请参见 isCharacters() 和text()。

qint64 QXmlStreamReader::lineNumber() const

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

另请参阅 columnNumber() 和characterOffset()。

QStringView QXmlStreamReader::name() const

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

另请参阅 namespaceUri() 和qualifiedName()。

QXmlStreamNamespaceDeclarations QXmlStreamReader::namespaceDeclarations() const

如果 `tokenType()` 的返回值为 `StartElement`，则该函数返回该元素的命名空间声明；否则返回一个空向量。

QXmlStreamNamespaceDeclarations 类被定义为QXmlStreamNamespaceDeclaration 的QList 。

另请参阅 addExtraNamespaceDeclaration() 和addExtraNamespaceDeclarations()。

QStringView QXmlStreamReader::namespaceUri() const

返回StartElement 或EndElement 的namespaceUri。

另请参阅 name() 和qualifiedName()。

QXmlStreamNotationDeclarations QXmlStreamReader::notationDeclarations() const

如果 `tokenType()` 的值为 `DTD`，则该函数返回 DTD 的标记声明；否则返回一个空向量。

QXmlStreamNotationDeclarations 类被定义为QXmlStreamNotationDeclaration 的QList 。

QStringView QXmlStreamReader::prefix() const

返回StartElement 或EndElement 的前缀。

另请参阅 name() 和qualifiedName()。

QStringView QXmlStreamReader::processingInstructionData() const

返回ProcessingInstruction 的数据。

QStringView QXmlStreamReader::processingInstructionTarget() const

返回ProcessingInstruction 的对象。

QStringView QXmlStreamReader::qualifiedName() const

返回StartElement 或EndElement 的限定名称；

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

另请参阅 name()、prefix() 和namespaceUri()。

void QXmlStreamReader::raiseError(const QString &message = QString())

抛出一个自定义错误，并可选地包含错误message 。

另请参阅 error() 和errorString()。

QString QXmlStreamReader::readElementText(QXmlStreamReader::ReadElementTextBehaviour behaviour = ErrorOnUnexpectedElement)

当读取到StartElement 时调用的便捷函数。该函数会持续读取直到遇到相应的EndElement ，并返回两者之间的所有文本。若无错误，调用此函数后，当前令牌（参见tokenType())为EndElement 。

当读取到Characters 或EntityReference 令牌时，该函数会将text() 拼接进去，但会跳过ProcessingInstruction 和Comment 。如果当前令牌不是StartElement ，则返回空字符串。

behaviour 定义了在读取到EndElement 之前若读取到其他内容时应如何处理。该函数可以包含子元素的文本（例如对 HTML 很有用）、忽略子元素，或者抛出UnexpectedElementError 异常并返回迄今为止读取的内容（默认行为）。

QXmlStreamReader::TokenType QXmlStreamReader::readNext()

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

除一种情况外，一旦 readNext() 报告了error()，就无法继续读取 XML 流。此时，atEnd() 将返回true ，hasError() 将返回true ，而本函数将返回QXmlStreamReader::Invalid 。

例外情况是当error()返回PrematureEndOfDocumentError 时。当达到一个本应格式正确的XML片段的末尾，但该片段并不代表完整的XML文档时，会报告此错误。 在这种情况下，如果流是从 `QByteArray` 读取的，可以通过调用 `addData()` 来添加下一个 XML 片段，从而恢复解析；如果流是从 `device()` 读取的，则可以通过等待更多数据到达来恢复解析。

另请参阅 tokenType() 和tokenString()。

bool QXmlStreamReader::readNextStartElement()

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

当前元素是指与最近解析的起始元素匹配、且其对应的结束元素尚未被解析到的元素。当解析器到达结束元素时，当前元素将变为父元素。

这是一个便捷函数，适用于您仅关注解析 XML 元素的情况。QXmlStream 书签示例中广泛使用了此函数。

另请参阅 readNext()。

[since 6.10] QString QXmlStreamReader::readRawInnerData()

读取并返回当前元素的原始内部 XML 内容。此函数可用于检索嵌入在元素内的完整内容，包括嵌套标签、文本、注释、处理指令、CDATA 段及其他标记——同时保留原始的 XML 结构。

当前元素是指与最近解析的起始元素匹配，且尚未遇到匹配结束元素的那个元素。当解析器到达结束元素时，当前元素将变为父元素。

该函数首次出现在 Qt 6.10 中。

void QXmlStreamReader::setDevice(QIODevice *device)

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

另请参阅 device() 和clear()。

void QXmlStreamReader::setEntityExpansionLimit(int limit)

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

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

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

最小值为 1，以支持内置的 XML 实体（< 等）。

另请参阅 entityExpansionLimit 。

void QXmlStreamReader::setEntityResolver(QXmlStreamEntityResolver *resolver)

将resolver 转换为新的entityResolver()。

流读取器不会接管解析器的所有权。调用方有责任确保在流读取器对象的整个生命周期内，或者直到设置了另一个解析器或nullptr 之前，该解析器始终有效。

另请参阅 entityResolver()。

void QXmlStreamReader::skipCurrentElement()

读取至当前元素的末尾，跳过所有子节点。此函数可用于跳过未知元素。

当前元素是指与最近解析的起始元素匹配，且尚未遇到与其匹配的结束元素的元素。当解析器到达结束元素时，当前元素将变为父元素。

QStringView QXmlStreamReader::text() const

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

QString QXmlStreamReader::tokenString() const

返回读取器当前的标记，格式为字符串。

另请参阅 tokenType()。

QXmlStreamReader::TokenType QXmlStreamReader::tokenType() const

返回当前令牌的类型。

还可以通过以下便捷函数查询当前令牌：isStartDocument()、isEndDocument()、isStartElement()、isEndElement()、isCharacters()、isComment()、isDTD()、isEntityReference() 以及isProcessingInstruction()。

另请参阅 tokenString()。