PySide6.QtXml.QDomDocument¶

class QDomDocument¶

QDomDocument 类表示一个 XML 文档。More_…

概要¶

方法¶

def __init__()
def createAttribute()
def createAttributeNS()
def createCDATASection()
def createComment()
def createDocumentFragment()
def createElement()
def createElementNS()
def createEntityReference()
def createProcessingInstruction()
def createTextNode()
def doctype()
def documentElement()
def elementById()
def elementsByTagName()
def elementsByTagNameNS()
def implementation()
def importNode()
def setContent()
def toByteArray()
def toString()

注意

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

详细描述¶

警告

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

QDomDocument 类代表整个 XML 文档。从概念上讲，它是文档树的根，并提供了对文档数据的主要访问。

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

解析后的XML在内部由对象树表示，可以使用各种QDom类访问。所有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()

有关文档对象模型的更多信息，请参阅文档对象模型（DOM）Level 1和Level 2 Core规范。

另请参阅

DOM书签应用程序

class ParseOption¶

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

常量

描述

QDomDocument.ParseOption.Default

未设置任何解析选项。

QDomDocument.ParseOption.UseNamespaceProcessing

启用了命名空间处理。

QDomDocument.ParseOption.PreserveSpacingOnlyNodes

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

另请参阅

setContent()

常量	描述
QDomDocument.ParseOption.Default	未设置任何解析选项。
QDomDocument.ParseOption.UseNamespaceProcessing	启用了命名空间处理。
QDomDocument.ParseOption.PreserveSpacingOnlyNodes	仅包含空白字符的文本节点将被保留。

在6.5版本中添加。

__init__()¶

构建一个空文档。

__init__(document)

Parameters:: 文档 – QDomDocument

构造document的副本。

复制的数据是共享的（浅拷贝）：修改一个节点也会改变另一个。如果你想进行深拷贝，请使用cloneNode()。

__init__(doctype)

Parameters:: doctype – QDomDocumentType

创建一个带有文档类型 doctype 的文档。

另请参阅

createDocumentType()

__init__(name)

Parameters:: name – str

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

createAttribute(name)¶

Parameters:: name – str
Return type:: QDomAttr

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

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

另请参阅

createAttributeNS()

createAttributeNS(nsURI, qName)¶

Parameters:

nsURI – str
qName – str

Return type:

QDomAttr

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

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

另请参阅

createAttribute()

createCDATASection(data)¶

Parameters:: data – 字符串
Return type:: QDomCDATASection

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

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

另请参阅

appendChild() insertBefore() insertAfter()

createComment(data)¶

Parameters:: data – 字符串
Return type:: QDomComment

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

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

另请参阅

appendChild() insertBefore() insertAfter()

createDocumentFragment()¶

Return type:: QDomDocumentFragment

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

createElement(tagName)¶

Parameters:: tagName – str
Return type:: QDomElement

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

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

另请参阅

createElementNS() appendChild() insertBefore() insertAfter()

createElementNS(nsURI, qName)¶

Parameters:

nsURI – str
qName – str

Return type:

QDomElement

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

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

另请参阅

createElement()

createEntityReference(name)¶

Parameters:: name – str
Return type:: QDomEntityReference

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

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

另请参阅

appendChild() insertBefore() insertAfter()

createProcessingInstruction(target, data)¶

Parameters:

target – str
data – 字符串

Return type:

QDomProcessingInstruction

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

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

另请参阅

appendChild() insertBefore() insertAfter()

createTextNode(data)¶

Parameters:: data – 字符串
Return type:: QDomText

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

如果 value 包含无法作为XML文档字符数据存储的字符（即使以字符引用的形式），此函数的行为将由 InvalidDataPolicy 控制。

另请参阅

appendChild() insertBefore() insertAfter()

doctype()¶

Return type:: QDomDocumentType

返回此文档的文档类型。

documentElement()¶

Return type:: QDomElement

返回文档的根元素。

elementById(elementId)¶

Parameters:: elementId – str
Return type:: QDomElement

返回ID等于elementId的元素。如果未找到具有该ID的元素，此函数将返回一个null element。

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

elementsByTagName(tagname)¶

Parameters:: tagname – str
Return type:: QDomNodeList

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

另请参阅

elementsByTagNameNS() elementsByTagName()

elementsByTagNameNS(nsURI, localName)¶

Parameters:

nsURI – str
localName – str

Return type:

QDomNodeList

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

另请参阅

elementsByTagName() elementsByTagNameNS()

implementation()¶

Return type:: QDomImplementation

返回一个QDomImplementation对象。

importNode(importedNode, deep)¶

Parameters:

importedNode – QDomNode
deep – 布尔值

Return type:

QDomNode

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

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

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

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

节点类型	行为
`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`	文本被复制到新节点。

setContent(data[, options=QDomDocument.ParseOption.Default])¶

Parameters:

data – 字符串
options – ParseOption 的组合

Return type:

ParseResult

setContent(device[, options=QDomDocument.ParseOption.Default])

Parameters:

设备 – QIODevice
options – ParseOption 的组合

Return type:

ParseResult

setContent(reader[, options=QDomDocument.ParseOption.Default])

Parameters:

reader – QXmlStreamReader
options – ParseOption 的组合

Return type:

ParseResult

setContent(dev)

Parameters:: 开发 – QIODevice
Return type:: (retval, errorMsg, errorLine, errorColumn)

注意

此函数已弃用。

这是一个重载函数。

使用返回ParseResult的重载代替。

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

不执行命名空间处理。

setContent(text)

Parameters:: 文本 – QByteArray
Return type:: (retval, errorMsg, errorLine, errorColumn)

注意

此函数已弃用。

这是一个重载函数。

请使用返回ParseResult的重载方法。

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

不执行命名空间处理。

setContent(text)

Parameters:: 文本 – str
Return type:: (retval, errorMsg, errorLine, errorColumn)

注意

此函数已弃用。

这是一个重载函数。

使用返回ParseResult的重载代替。

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

也没有执行命名空间处理。

setContent(dev, namespaceProcessing)

Parameters:

dev – QIODevice
namespaceProcessing – bool

Return type:

(retval, errorMsg, errorLine, errorColumn)

注意

此函数已弃用。

这是一个重载函数。

请使用带有ParseOptions的重载方法。

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

注意

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

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

Parameters:

reader – QXmlStreamReader
namespaceProcessing – bool
errorMsg – str
errorLine – int
errorColumn – int

Return type:

布尔

注意

此函数已弃用。

这是一个重载函数。

请使用带有ParseOptions的重载方法。

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

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

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

另请参阅

QXmlStreamReader

setContent(text, namespaceProcessing)

Parameters:

文本 – QByteArray
namespaceProcessing – bool

Return type:

(retval, errorMsg, errorLine, errorColumn)

注意

此函数已弃用。

请使用带有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, namespaceProcessing)

Parameters:

文本 – str
namespaceProcessing – bool

Return type:

(retval, errorMsg, errorLine, errorColumn)

注意

此函数已弃用。

这是一个重载函数。

请使用带有ParseOptions的重载方法。

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

toByteArray([indent=1])¶

Parameters:: 缩进 – int
Return type:: QByteArray

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

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

另请参阅

toString()

toString([indent=1])¶

Parameters:: 缩进 – int
Return type:: 字符串

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

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

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

class ParseResult¶

注意

详细描述¶

PySide6.QtXml.QDomDocument.ParseResult.errorMessage¶

PySide6.QtXml.QDomDocument.ParseResult.errorLine¶

PySide6.QtXml.QDomDocument.ParseResult.errorColumn¶