class QDomDocument#

QDomDocument 类表示一个 XML 文档。 更多信息…

Inheritance diagram of PySide6.QtXml.QDomDocument

摘要#

方法#

注意事项

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

详细信息#

警告

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

QDomDocument 类表示整个XML文档。从概念上讲，它是文档树的根，提供对文档数据的初步访问。

由于元素、文本节点、注释、处理指令等不能存在于文档之外，因此文档类还包含创建这些对象的工厂函数。生成的节点对象有一个ownerDocument()函数，该函数将它们与创建它们的文档的上下文关联起来。最常使用的DOM类是QDomNode、QDomDocument、QDomElement和QDomText。

内部通过使用多种QDom类来访问的对象树来表示解析的XML。所有QDom类只引用内部树中的对象。一旦删除最后一个引用它们的QDom对象或QDomDocument本身，DOM树中的内部对象将被删除。

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

QDomDocument类具有创建文档数据的几个函数，例如createElement()、createTextNode()、createComment()、createCDATASection()、createProcessingInstruction()、createAttribute()和createEntityReference()。其中一些函数有支持命名空间的版本，即createElementNS()和createAttributeNS()。createDocumentFragment()函数用于保存文档的部分内容；这对于操作复杂文档非常有用。

文档的全部内容都是通过 setContent() 来设置的。此函数将其作为XML文档解析的字符串，并创建表示文档的DOM树。可以通过 documentElement() 来访问根元素。可以通过 toString() 获取文档的文本表示。

注意事项

如果XML文档很大，DOM树可能会预留大量内存。对于此类文档，QXmlStreamReader类可能是更好的解决方案。

可以通过 importNode() 将另一个文档中的节点插入到文档中。

可以通过 elementsByTagName() 或 elementsByTagNameNS() 获取具有特定标签的所有元素列表。

QDom类通常如下使用

doc = QDomDocument("mydocument")
file = QFile("mydocument.xml")
if not file.open(QIODevice.ReadOnly):
    return
if not doc.setContent(file):
    file.close()
    return

file.close()
# print out the element names of all elements that are direct children
# of the outermost element.
docElem = doc.documentElement()
n = docElem.firstChild()
while not n.isNull():
    e = n.toElement() # try to convert the node to an element.
    if not e.isNull():
        print(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
elem = doc.createElement("img")
elem.setAttribute("src", "myimage.png")
docElem.appendChild(elem)

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

使用DOM创建文档的代码如下

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

有关Document Object Model的更多信息，请参阅Document Object Model (DOM) Level 1 和 Level 2 Core 规范。

另见

DOM书签应用程序

class ParseOption#

(继承 enum.Flag) 这个枚举描述了可以在使用 setContent() 方法解析XML文档时使用的可能选项。

常数

描述

QDomDocument.ParseOption.Default

未设置解析选项。

QDomDocument.ParseOption.UseNamespaceProcessing

命名空间处理已启用。

QDomDocument.ParseOption.PreserveSpacingOnlyNodes

仅包含空格字符的文本节点被保留。

另见

setContent()

新版本6.5。

__init__(x)#
参数:

x – QDomDocument

构造并复制 x。

复制的数据是共享的（浅复制）：修改一个节点也会更改另一个节点。如果你想要创建一个深层次的复制，请使用 cloneNode() .

__init__(doctype)
参数:

doctype – QDomDocumentType

创建具有文档类型 doctype 的文档。

__init__(name)
参数:

name – str

创建一个文档，并将文档类型的名称设置为 name。

__init__()

构造一个空文档。

createAttribute(name)#
参数:

name – str

返回类型：

QDomAttr

创建一个名为 name 的新属性，可以将其插入到元素中，例如使用 setAttributeNode() .

如果 name 不是一个有效的 XML 名称，该函数的行为由 InvalidDataPolicy 控制。

createAttributeNS(nsURI, qName)#
参数:

  • nsURI – str

  • qName – str

返回类型：

QDomAttr

创建一个带有命名空间支持的新属性，可以将其插入到元素中。该属性的名称为 qName，命名空间 URI 为 nsURI。此函数还设置 prefix() 和 localName() 为适当值（根据 qName）。

如果 qName 不是一个有效的 XML 名称，该函数的行为由 InvalidDataPolicy 控制。

createCDATASection(data)#
参数:

data – str

返回类型：

QDomCDATASection

为字符串 value 创建新的 CDATA 部分，可以将其插入到文档中，例如使用 appendChild() .

如果 value 包含无法存储在 CDATA 部分中的字符，该函数的行为由 InvalidDataPolicy 控制。

createComment(数据)#
参数:

data – str

返回类型：

QDomComment

为字符串 value 创建一个新注释，可以插入到文档中，例如使用 appendChild() .

如果 value 包含不能存储在 XML 注释中的字符，则此函数的行为由 InvalidDataPolicy 控制。

createDocumentFragment()#
返回类型：

QDomDocumentFragment

创建一个新文档片段，可用于保存文档的部分内容，例如在进行文档树的复杂操作时。

createElement(tagName)#
参数:

tagName – str

返回类型：

QDomElement

创建一个名为 tagName 的新元素，可以插入到 DOM 树中，例如使用 appendChild() .

如果 tagName 不是一个有效的 XML 名称，则此函数的行为由 InvalidDataPolicy 控制。

createElementNS(nsURI, qName)#
参数:

  • nsURI – str

  • qName – str

返回类型：

QDomElement

创建一个具有命名空间支持的新元素，可以将其插入到DOM树中。该元素的名称为 qName，命名空间URI为 nsURI。此函数同时还将 prefix() 和 localName() 设置为适当的值（相对于 qName）。

如果 qName 是空字符串，则无论是否设置了无效数据策略，都返回一个空元素。

createEntityReference(name)#
参数:

name – str

返回类型：

QDomEntityReference

创建一个名为 name 的新实体引用，可以将其插入到文档中，例如使用 appendChild() 。

如果 name 不是一个有效的 XML 名称，该函数的行为由 InvalidDataPolicy 控制。

createProcessingInstruction(target, data)#
参数:

  • 目标 – str

  • data – str

返回类型：

QDomProcessingInstruction

创建一个可以插入到文档中的新处理指令，例如使用 appendChild() 。此函数将处理指令的目标设置为 target 并将数据设置为 data。

如果 target 不是一个有效的XML名称，或者数据包含不能在处理指令中出现的字符，则该函数的行为由 InvalidDataPolicy 控制。

createTextNode(data)#
参数:

data – str

返回类型：

QDomText

为字符串 value 创建一个文本节点，可以将其插入到文档树中，例如使用 appendChild() 。

如果 value 包含不能用作XML文档字符数据的字符（即使是以字符引用的形式），则该函数的行为由 InvalidDataPolicy 控制。

doctype()#
返回类型：

QDomDocumentType

返回该文档的文档类型。

documentElement()#
返回类型：

QDomElement

返回文档的根元素。

elementById(elementId)#
参数:

elementId – 字符串

返回类型：

QDomElement

返回ID等于 elementId 的元素。如果没有找到具有该ID的元素，则此函数返回一个 空元素。

由于QDomClasses不知道哪些属性是元素ID，因此此函数始终返回一个 空元素。这可能在未来的版本中发生变化。

elementsByTagName(tagname)#
参数:

tagname – 字符串

返回类型：

QDomNodeList

返回一个包含文档中所有名称为 tagname 的元素的 QDomNodeList。节点列表的顺序是节点在元素树的前序遍历中遇到的顺序。

elementsByTagNameNS(nsURI, localName)#
参数:

  • nsURI – str

  • localName – 字符串

返回类型：

QDomNodeList

返回一个包含文档中所有具有本地名 localName 和命名空间URI nsURI 的元素的 QDomNodeList。节点列表的顺序是节点在元素树的前序遍历中遇到的顺序。

implementation()#
返回类型：

QDomImplementation

返回一个 QDomImplementation 对象。

importNode(importedNode, deep)#
参数:

  • importedNode – QDomNode

  • deep – 布尔值

返回类型：

QDomNode

从另一份文档导入节点 importedNode 到本文档中。 importedNode 仍保留在原始文档中；此函数创建一个副本，可以在本文档中使用。

此函数返回属于本文档的导入节点。返回的节点没有父节点。无法导入 QDomDocument 和 QDomDocumentType 节点。在这些情况下，此函数返回一个 null 节点 。

如果 importedNode 是一个 null 节点 ，则返回一个空节点。

如果 deep 为 true，此函数不仅导入节点 importedNode，还导入其整个子树；如果为 false，则只导入 importedNode。参数 deep 对 QDomAttr 和 QDomEntityReference 节点没有影响，因为 QDomAttr 节点的后代总是导入，而 QDomEntityReference 节点的后代从未导入。

此函数的行为根据节点类型略有不同

节点类型

行为

QDomAttr

将拥有元素设置为 0，并在生成的属性中将指定的标志设置为 true。对于属性节点，总是导入 importedNode 的整个子树：deep 没有影响。

QDomDocument

不能导入文档节点。

QDomDocumentFragment

如果 deep 为 true，则此函数导入整个文档片段；否则只生成一个空文档片段。

QDomDocumentType

不能导入文档类型节点。

QDomElement

导入的属性是 specified() 为 true 的属性，其他属性则不导入。如果 deep 为 true，则此函数还导入 importedNode 的子树；否则只导入元素节点（以及一些属性，见上文）。

QDomEntity

可以导入实体节点，但目前在 DOM 2 级别中，由于文档类型为只读，无法使用它们。

QDomEntityReference

实体引用节点的后代永远不会导入：deep 没有影响。

QDomNotation

符号节点可以导入，但目前已经没有使用它们的方法，因为文档类型在DOM 2级别中是只读的。

QDomProcessingInstruction

处理指令的目标和值将复制到新节点中。

QDomText

文本将复制到新节点中。

QDomCDATASection

文本将复制到新节点中。

QDomComment

文本将复制到新节点中。

另见

setAttribute() insertBefore() insertAfter() replaceChild() removeChild() appendChild()

setContent(dev)#
参数:

dev – QIODevice

返回类型：

(返回值，错误消息，错误行，错误列)

这是一个重载函数。

请使用返回 ParseResult 的重载。

此函数从IO设备 dev 读取XML文档，如果内容被成功解析则返回true；否则返回 false。

不执行命名空间处理。

setContent(dev, namespaceProcessing)
参数:

  • dev – QIODevice

  • namespaceProcessing – bool

返回类型：

(返回值，错误消息，错误行，错误列)

这是一个重载函数。

请使用接受 ParseOptions 的重载。

此函数从IO设备 dev 读取XML文档，如果内容被成功解析则返回true；否则返回 false。

注意事项

此方法将尝试如果 dev 还未打开则在只读模式下打开它。在这种情况下，调用者负责调用关闭。在 Qt 7 中这将会改变，它将不再打开 dev。因此，在调用 setContent 之前，应用程序应该自己打开设备。

setContent(reader, namespaceProcessing[, errorMsg=None[, errorLine=None[, errorColumn=None]]])
参数:

  • reader – QXmlStreamReader

  • namespaceProcessing – bool

  • errorMsg – str

  • errorLine – int

  • errorColumn – int

返回类型：

bool

这是一个重载函数。

请使用接受 ParseOptions 的重载。

此函数从 QXmlStreamReader reader 读取XML文档并对其解析。如果内容被成功解析则返回 true；否则返回 false。

如果 namespaceProcessing 设置为 true，解析器会识别 XML 文件中的命名空间，并将前缀名、局部名称和命名空间 URI 设置为适当的值。如果 namespaceProcessing 设置为 false，则解析器在读取 XML 文件时不会进行命名空间处理。

如果发生解析错误，错误消息将被放置在 * errorMsg 中，行号在 * errorLine 中，列号在 * errorColumn 中（除非相关指针设置为 nullptr）。

setContent(text)
参数:

text – QByteArray

返回类型：

(返回值，错误消息，错误行，错误列)

这是一个重载函数。

请使用返回 ParseResult 的重载。

此函数从字节数组 buffer 中读取 XML 文档，如果内容成功解析则返回 true；否则返回 false。

不执行命名空间处理。

setContent(text), namespaceProcessing)
参数:

  • text – QByteArray

  • namespaceProcessing – bool

返回类型：

(返回值，错误消息，错误行，错误列)

请使用接受 ParseOptions 的重载。

这是一个重载函数。

此函数从字节数组 data 中解析 XML 文档并将其设置为文档内容。它尝试检测文档所要求的编码，以满足 XML 规范的要求。

如果 namespaceProcessing 设置为 true，解析器会识别 XML 文件中的命名空间，并将前缀名称、局部名称和命名空间 URI 设置为适当的值。如果 namespaceProcessing 设置为 false，解析器在读取 XML 文件时不会进行命名空间处理。

如果发生解析错误，此函数返回 false 并将错误消息放置在 * errorMsg 中，行号在 * errorLine 中，列号在 * errorColumn 中（除非相关指针设置为 nullptr）；否则此函数返回 true。

如果 namespaceProcessing 设置为 true，函数 prefix() 将为所有元素和属性返回一个字符串。如果元素或属性没有前缀，它将返回一个空字符串。

只包含空白字符的文本节点将被删除，不会出现在 QDomDocument 中。

如果 namespaceProcessing 为 false，函数 prefix()、localName() 和 namespaceURI() 将返回一个空字符串。

实体引用的处理方式如下

  • 包含内部通用实体和内容中出现的字符实体的引用。结果是一个 QDomText 节点，其中引用已被对应的实体值所替换。

  • 包含内部子集中出现的参数实体引用。结果显示为 QDomDocumentType 节点，其中包含实体和注释声明，引用已替换为对应的实体值。

  • 任何未在内部子集中定义的通用解析实体引用，在内容中出现时，表示为 QDomEntityReference 节点。

  • 任何未在内部子集中定义且出现在内容外的解析实体引用将以空字符串替换。

  • 任何未解析的实体引用将用空字符串替换。

另见

namespaceURI() localName() prefix() isEmpty()

setContent(text)
参数:

text - str

返回类型：

(返回值，错误消息，错误行，错误列)

这是一个重载函数。

请使用返回 ParseResult 的重载。

此函数从字符串 text 中读取 XML 文档，如果内容成功解析则返回 true，否则返回 false。由于 text 已经是一个 Unicode 字符串，不需要进行编码检测。

也不会执行命名空间处理。

setContent(text), namespaceProcessing)
参数:

  • text - str

  • namespaceProcessing – bool

返回类型：

(返回值，错误消息，错误行，错误列)

这是一个重载函数。

请使用接受 ParseOptions 的重载。

此函数从字符串 text 中读取 XML 文档，如果内容成功解析则返回 true，否则返回 false。由于 text 已经是一个 Unicode 字符串，不会进行编码检测。

toByteArray([arg__1=1])#
参数:

arg__1 - int

返回类型：

QByteArray

将解析的文档转换回其文本表示形式，并返回一个包含 UTF-8 编码数据的 QByteArray。

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

另见

toString()

toString([arg__1=1])#
参数:

arg__1 - int

返回类型：

字符串

将解析的文档转换回其文本表示形式。

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

如果 indent 为 -1，则不添加任何空白。