就业培训     下载中心     Wiki     联络 登录   注册
  1. 首页
  2. Qt 6.5.1
  3. Qt XML
  4. C++ 类
  5. QDomDocument

QDomDocument 类

QDomDocument 类表示 XML (可扩展标记语言) 文档。 更多...

头： #include <QDomDocument>
CMake: find_package(Qt6 REQUIRED COMPONENTS Xml)
target_link_libraries(mytarget PRIVATE Qt6::Xml)
qmake: QT += xml
继承： QDomNode

注意： 此类的所有函数 可重入 .

公共类型

struct ParseResult
enum class ParseOption { Default, UseNamespaceProcessing, PreserveSpacingOnlyNodes }
flags ParseOptions

公共函数

QDomDocument ()
QDomDocument (const QString & name )
QDomDocument (const QDomDocumentType & doctype )
QDomDocument (const QDomDocument & x )
~QDomDocument ()
QDomAttr createAttribute (const QString & name )
QDomAttr createAttributeNS (const QString & nsURI , const QString & qName )
QDomCDATASection createCDATASection (const QString & value )
QDomComment createComment (const QString & value )
QDomDocumentFragment createDocumentFragment ()
QDomElement createElement (const QString & tagName )
QDomElement createElementNS (const QString & nsURI , const QString & qName )
QDomEntityReference createEntityReference (const QString & name )
QDomProcessingInstruction createProcessingInstruction (const QString & target , const QString & data )
QDomText createTextNode (const QString & value )
QDomDocumentType doctype () const
QDomElement documentElement () const
QDomElement elementById (const QString & elementId )
QDomNodeList elementsByTagName (const QString & tagname ) const
QDomNodeList elementsByTagNameNS (const QString & nsURI , const QString & localName )
QDomImplementation 实现 () const
QDomNode importNode (const QDomNode & importedNode , bool deep )
QDomNode::NodeType nodeType () const
QDomDocument::ParseResult setContent (const QByteArray & data , QDomDocument::ParseOptions options = ParseOption::Default)
QDomDocument::ParseResult setContent (QAnyStringView data , QDomDocument::ParseOptions options = ParseOption::Default)
QDomDocument::ParseResult setContent (QIODevice * device , QDomDocument::ParseOptions options = ParseOption::Default)
QDomDocument::ParseResult setContent (QXmlStreamReader * reader , QDomDocument::ParseOptions options = ParseOption::Default)
QByteArray toByteArray (int indent = 1) const
QString toString (int indent = 1) const
QDomDocument & operator= (const QDomDocument & x )

详细描述

QDomDocument 类表示整个 XML 文档。概念上，它是文档树根，并提供对文档数据的首要访问。

由于元素、文本节点、注释、处理指令、等不能存在于文档上下文之外，因此文档类还包含创建这些对象所需的工厂函数。创建的节点对象拥有 ownerDocument () 函数将它们与在其中创建它们的上下文文档关联。最常用的 DOM 类是 QDomNode , QDomDocument, QDomElement and QDomText .

经剖析的 XML 通过对象树在内部表示，可以使用各种 QDom 类访问它们。所有 QDom 类只 reference 对象在内部树中。一旦 DOM 树内部对象被删除，最后引用它们的 QDom 对象或 QDomDocument 本身被删除。

元素、文本节点、等的创建是使用此类中提供的各种工厂函数完成的。使用 QDom 类默认构造函数只会导致无法操纵或插入文档的空对象。

QDomDocument 类拥有用于创建文档数据的几个函数，例如 createElement (), createTextNode (), createComment (), createCDATASection (), createProcessingInstruction (), createAttribute () 和 createEntityReference ()。其中某些函数拥有支持名称空间的版本，即 createElementNS () 和 createAttributeNS ()。 createDocumentFragment () 函数用于保持文档部分；这对操纵复杂文档很有用。

整个文档内容的设置采用 setContent ()。此函数剖析作为 XML 文档传递的字符串，并创建表示文档的 DOM 树。根元素是可用的使用 documentElement ()。可以获得文档的正文表示使用 toString ().

注意： DOM 树可能最终预留大量内存，若 XML 文档很大。对于这种文档， QXmlStreamReader 或 QXmlQuery 类可能是更优解决方案。

它是可能的，将来自另一文档的节点插入文档使用 importNode ().

可以获取拥有特定标签的所有元素的列表使用 elementsByTagName () 或采用 elementsByTagNameNS ().

QDom 类的使用通常如下所示： 

QDomDocument doc("mydocument");
QFile file("mydocument.xml");
if (!file.open(QIODevice::ReadOnly))
    return;
if (!doc.setContent(&file)) {
    file.close();
    return;
}
file.close();
// print out the element names of all elements that are direct children
// of the outermost element.
QDomElement docElem = doc.documentElement();
QDomNode n = docElem.firstChild();
while(!n.isNull()) {
    QDomElement e = n.toElement(); // try to convert the node to an element.
    if(!e.isNull()) {
        cout << qPrintable(e.tagName()) << '\n'; // the node really is an element.
    }
    n = n.nextSibling();
}
// Here we append a new element to the end of the document
QDomElement elem = doc.createElement("img");
elem.setAttribute("src", "myimage.png");
docElem.appendChild(elem);

一旦 doc and elem 超出作用域，表示 XML 文档的整个内部树就会被删除。

要使用 DOM 创建文档，所用代码像这样： 

QDomDocument doc;
QDomElement root = doc.createElement("MyML");
doc.appendChild(root);
QDomElement tag = doc.createElement("Greeting");
root.appendChild(tag);
QDomText t = doc.createTextNode("Hello World");
tag.appendChild(t);
QString xml = doc.toString();

有关文档对象模型的进一步信息，见 DOM (文档对象模型) 级别 1 and 级别 2 核心 规范。

另请参阅 DOM Bookmarks Application and 简单 DOM 模型范例 .

成员类型文档编制

[since 6.5] enum class QDomDocument:: ParseOption
flags QDomDocument:: ParseOptions

This enum describes the possible options that can be used when parsing an XML document using the setContent () 方法。

常量 值 描述
QDomDocument::ParseOption::Default 0x00 No parse options are set.
QDomDocument::ParseOption::UseNamespaceProcessing 0x01 Namespace processing is enabled.
QDomDocument::ParseOption::PreserveSpacingOnlyNodes 0x02 Text nodes containing only spacing characters are preserved.

该枚举在 Qt 6.5 引入 (或被修改)。

The ParseOptions type is a typedef for QFlags <ParseOption>. It stores an OR combination of ParseOption values.

另请参阅 setContent ().

成员函数文档编制

[since 6.5] QDomDocument::ParseResult QDomDocument:: setContent ( QAnyStringView data , QDomDocument::ParseOptions options = ParseOption::Default)

[since 6.5] QDomDocument::ParseResult QDomDocument:: setContent ( QIODevice * device , QDomDocument::ParseOptions options = ParseOption::Default)

[since 6.5] QDomDocument::ParseResult QDomDocument:: setContent ( QXmlStreamReader * reader , QDomDocument::ParseOptions options = ParseOption::Default)

[since 6.5] QDomDocument::ParseResult QDomDocument:: setContent (const QByteArray & data , QDomDocument::ParseOptions options = ParseOption::Default)

此函数剖析 XML 文档从字节数组 data , string view text , IO device , or stream reader and sets it as the content of the document. It tries to detect the encoding of the document, in accordance with the XML specification. Returns the result of parsing in ParseResult , which explicitly converts to bool .

可以使用 options parameter to specify different parsing options, for example, to enable namespace processing, etc.

By default, namespace processing is disabled. If it's disabled, the parser does no namespace processing when it reads the XML file. The functions QDomNode::prefix (), QDomNode::localName () 和 QDomNode::namespaceURI () 返回空字符串。

If namespace processing is enabled via the parse options , the parser recognizes namespaces in the XML file and sets the prefix name, local name and namespace URI to appropriate values. The functions QDomNode::prefix (), QDomNode::localName () 和 QDomNode::namespaceURI () return a string for all elements and attributes and return an empty string if the element or attribute has no prefix.

仅剥离由空白组成的文本节点，且不会出现在 QDomDocument . Since Qt 6.5, one can pass QDomDocument::ParseOption::PreserveSpacingOnlyNodes as a parse option, to specify that spacing-only text nodes must be preserved.

实体引用处理如下：

  • 包括出现在内容中的内部一般实体和字符实体的引用。结果是 QDomText 节点，具有被其相应实体值所替换的引用。
  • 包括出现在内部子集中的参数实体的引用。结果是 QDomDocumentType 节点，包含实体和符号声明 (具有被其相应实体值所替换的引用)。
  • 未在内部子集中定义且出现在内容中的任何一般剖析实体引用，被表示成 QDomEntityReference 节点。
  • 任何未在内部子集中定义且出现在内容之外的经剖析实体引用，都被替换为空字符串。
  • 任何未剖析实体引用被替换为空字符串。

注意： The overload taking IO device will try to open it in read-only mode if it is not already open. In that case, the caller is responsible for calling close. This will change in Qt 7, which will no longer open the IO device . Applications should therefore open the device themselves before calling setContent ().

该函数在 Qt 6.5 引入。

另请参阅 ParseResult and ParseOptions .

QDomDocument:: QDomDocument ()

构造空文档。

[explicit] QDomDocument:: QDomDocument (const QString & name )

创建文档并将文档类型名称设为 name .

[explicit] QDomDocument:: QDomDocument (const QDomDocumentType & doctype )

创建文档采用文档类型 doctype .

另请参阅 QDomImplementation::createDocumentType ().

QDomDocument:: QDomDocument (const QDomDocument & x )

构造副本为 x .

拷贝数据是共享的 (浅拷贝)：修改一节点也会改变另一节点。若想要做深拷贝，使用 cloneNode ().

QDomDocument:: ~QDomDocument ()

销毁对象并释放其资源。

QDomAttr QDomDocument:: createAttribute (const QString & name )

创建新属性称为 name 可以插入元素，如：使用 QDomElement::setAttributeNode ().

若 name 不是有效 XML 名称，此函数的行为被支配由 QDomImplementation::InvalidDataPolicy .

另请参阅 createAttributeNS ().

QDomAttr QDomDocument:: createAttributeNS (const QString & nsURI , const QString & qName )

创建具有名称空间支持，可以插入元素的新属性。属性名称为 qName 和名称空间 URI (统一资源标识符) 为 nsURI 。此特征还设置 QDomNode::prefix () 和 QDomNode::localName () 为适当值 (从属 qName ).

若 qName 不是有效 XML 名称，此函数的行为被支配由 QDomImplementation::InvalidDataPolicy .

另请参阅 createAttribute ().

QDomCDATASection QDomDocument:: createCDATASection (const QString & value )

创建新 CDATA 区间为字符串 value 可以插入文档，如：使用 QDomNode::appendChild ().

若 value 包含无法存储在 CDATA 区间的字符，此函数的行为被支配由 QDomImplementation::InvalidDataPolicy .

另请参阅 QDomNode::appendChild (), QDomNode::insertBefore ()，和 QDomNode::insertAfter ().

QDomComment QDomDocument:: createComment (const QString & value )

创建的新注释为字符串 value 可以插入文档，如：使用 QDomNode::appendChild ().

若 value 包含无法存储于 XML 注释中的字符，此函数的行为被支配由 QDomImplementation::InvalidDataPolicy .

另请参阅 QDomNode::appendChild (), QDomNode::insertBefore ()，和 QDomNode::insertAfter ().

QDomDocumentFragment QDomDocument:: createDocumentFragment ()

创建新的文档片段，可以用于保持文档的一部分，如：当对文档树做复杂操纵时。

QDomElement QDomDocument:: createElement (const QString & tagName )

创建的新元素称为 tagName 可以插入 DOM 树，如：使用 QDomNode::appendChild ().

若 tagName 不是有效 XML 名称，此函数的行为被支配由 QDomImplementation::InvalidDataPolicy .

另请参阅 createElementNS (), QDomNode::appendChild (), QDomNode::insertBefore ()，和 QDomNode::insertAfter ().

QDomElement QDomDocument:: createElementNS (const QString & nsURI , const QString & qName )

创建具有名称空间支持的新元素，可以插入 DOM 树。元素的名称为 qName 和名称空间 URI (统一资源标识符) 为 nsURI 。此特征还设置 QDomNode::prefix () 和 QDomNode::localName () 为适当值 (从属 qName ).

若 qName 为空字符串，返回 null 元素不管无效数据策略是否有设置。

另请参阅 createElement ().

QDomEntityReference QDomDocument:: createEntityReference (const QString & name )

创建新实体引用称为 name 可以插入文档，如：使用 QDomNode::appendChild ().

若 name 不是有效 XML 名称，此函数的行为被支配由 QDomImplementation::InvalidDataPolicy .

另请参阅 QDomNode::appendChild (), QDomNode::insertBefore ()，和 QDomNode::insertAfter ().

QDomProcessingInstruction QDomDocument:: createProcessingInstruction (const QString & target , const QString & data )

创建可以插入文档的新处理指令，如：使用 QDomNode::appendChild ()。此函数将处理指令目标设为 target 和数据到 data .

若 target 不是有效 XML 名称，或数据若包含不可以出现在处理指令中的字符，此函数的行为被支配由 QDomImplementation::InvalidDataPolicy .

另请参阅 QDomNode::appendChild (), QDomNode::insertBefore ()，和 QDomNode::insertAfter ().

QDomText QDomDocument:: createTextNode (const QString & value )

创建文本节点为字符串 value 可以插入文档树，如：使用 QDomNode::appendChild ().

若 value 包含不可以作为 XML 文档字符数据存储的字符 (即使按字符引用形式)，此函数的行为被支配由 QDomImplementation::InvalidDataPolicy .

另请参阅 QDomNode::appendChild (), QDomNode::insertBefore ()，和 QDomNode::insertAfter ().

QDomDocumentType QDomDocument:: doctype () const

返回此文档的文档类型。

QDomElement QDomDocument:: documentElement () const

返回文档的根元素。

QDomElement QDomDocument:: elementById (const QString & elementId )

返回的元素 ID 等于 elementId 。若未找到具有 ID 的元素，此函数返回 null 元素 .

由于 QDomClasses 不知道哪些属性是元素 ID，所以此函数始终返回 null 元素 。这在未来版本中可能改变。

QDomNodeList QDomDocument:: elementsByTagName (const QString & tagname ) const

返回 QDomNodeList ，包含文档中的所有元素具有名称 tagname 。节点列表次序是以预顺序遍历元素树时遇到它们的次序。

另请参阅 elementsByTagNameNS () 和 QDomElement::elementsByTagName ().

QDomNodeList QDomDocument:: elementsByTagNameNS (const QString & nsURI , const QString & localName )

返回 QDomNodeList ，包含文档中的所有元素具有本地名称 localName 和名称空间 URI (统一资源标识符) 为 nsURI 。节点列表次序是以预顺序遍历元素树时遇到它们的次序。

另请参阅 elementsByTagName () 和 QDomElement::elementsByTagNameNS ().

QDomImplementation QDomDocument:: 实现 () const

返回 QDomImplementation 对象。

QDomNode QDomDocument:: importNode (const QDomNode & importedNode , bool deep )

导入节点 importedNode 从另一文档到此文档。 importedNode 仍然在原文档中；此函数创建可在此文档中使用的副本。

此函数返回属于此文档的导入节点。返回节点没有父级。它是不可能的去导入 QDomDocument and QDomDocumentType 节点。在此情况下，该函数返回 null 节点 .

若 importedNode 是 null 节点 ，返回空节点。

若 deep 为 True，此函数不仅导入节点 importedNode 及其整个子树；若它为 false，仅 importedNode 被导入。自变量 deep 不起作用对 QDomAttr and QDomEntityReference 节点，因为后代的 QDomAttr 节点始终被导入而那些 QDomEntityReference 节点从不被导入。

此函数行为稍有不同，根据节点类型：

节点类型 行为
QDomAttr owner 元素被设为 0 并将生成属性中的指定标志设为 true。整个子树的 importedNode 始终为属性节点导入： deep 不起作用。
QDomDocument 无法导入文档节点。
QDomDocumentFragment 若 deep 为 True，此函数导入整个文档片段；否则它仅生成空文档片段。
QDomDocumentType 无法导入文档类型节点。
QDomElement 属性为 QDomAttr::specified () 为 true 也被导入，其它属性不被导入。若 deep 为 True，此函数还导入子树的 importedNode ；否则它只导入元素节点 (和一些属性，见上文)。
QDomEntity 实体节点可以导入，但目前没有办法使用它们，因为文档类型在 DOM 级别 2 中是只读的。
QDomEntityReference 实体引用节点的后代从不被导入： deep 不起作用。
QDomNotation 表示法节点可以导入，但目前没有办法使用它们，因为文档类型在 DOM 级别 2 中是只读的。
QDomProcessingInstruction 处理指令的目标和值被拷贝到新节点。
QDomText 文本被拷贝到新节点。
QDomCDATASection 文本被拷贝到新节点。
QDomComment 文本被拷贝到新节点。

另请参阅 QDomElement::setAttribute (), QDomNode::insertBefore (), QDomNode::insertAfter (), QDomNode::replaceChild (), QDomNode::removeChild ()，和 QDomNode::appendChild ().

QDomNode::NodeType QDomDocument:: nodeType () const

返回 DocumentNode .

QByteArray QDomDocument:: toByteArray ( int indent = 1) const

将经剖析文档转换回其正文表示并返回 QByteArray 包含编码为 UTF-8 的数据。

此函数使用 indent 作为缩进子元素的空格数量。

另请参阅 toString ().

QString QDomDocument:: toString ( int indent = 1) const

将经剖析文档转换回其正文表示。

此函数使用 indent 作为缩进子元素的空格数量。

若 indent 为 -1，根本不添加空白。

QDomDocument &QDomDocument:: operator= (const QDomDocument & x )

赋值 x 到此 DOM (文档对象模型) 文档。

拷贝数据是共享的 (浅拷贝)：修改一节点也会改变另一节点。若想要做深拷贝，使用 cloneNode ().

内容