QDomDocument Class
La clase QDomDocument representa un documento XML. Más información...
| Encabezado: | #include <QDomDocument> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Xml) target_link_libraries(mytarget PRIVATE Qt6::Xml) |
| qmake: | QT += xml |
| Heredan: | QDomNode |
- Lista de todos los miembros, incluidos los heredados
- Miembros obsoletos
- QDomDocument forma parte de las clases XML.
Nota: Todas las funciones de esta clase son reentrantes.
Tipos públicos
(since 6.5) struct | ParseResult |
(since 6.5) enum class | ParseOption { Default, UseNamespaceProcessing, PreserveSpacingOnlyNodes } |
| flags | ParseOptions |
Funciones públicas
| QDomDocument() | |
| QDomDocument(const QDomDocumentType &doctype) | |
| QDomDocument(const QString &name) | |
| QDomDocument(const QDomDocument &document) | |
| ~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 | implementation() const |
| QDomNode | importNode(const QDomNode &importedNode, bool deep) |
| QDomNode::NodeType | nodeType() const |
(since 6.5) QDomDocument::ParseResult | setContent(QAnyStringView text, QDomDocument::ParseOptions options = ParseOption::Default) |
(since 6.5) QDomDocument::ParseResult | setContent(QIODevice *device, QDomDocument::ParseOptions options = ParseOption::Default) |
(since 6.5) QDomDocument::ParseResult | setContent(QXmlStreamReader *reader, QDomDocument::ParseOptions options = ParseOption::Default) |
(since 6.5) QDomDocument::ParseResult | setContent(const QByteArray &data, QDomDocument::ParseOptions options = ParseOption::Default) |
| QByteArray | toByteArray(int indent = 1) const |
| QString | toString(int indent = 1) const |
| QDomDocument & | operator=(const QDomDocument &other) |
Descripción detallada
La clase QDomDocument representa el documento XML completo. Conceptualmente, es la raíz del árbol del documento y proporciona el acceso principal a los datos del mismo.
Dado que los elementos, los nodos de texto, los comentarios, las instrucciones de procesamiento, etc., no pueden existir fuera del contexto de un documento, la clase de documento también contiene las funciones de fábrica necesarias para crear estos objetos. Los objetos de nodo creados disponen de una función ` ownerDocument()` que los asocia al documento en cuyo contexto se crearon. Las clases DOM que se utilizarán con mayor frecuencia son QDomNode, QDomDocument, QDomElement y QDomText.
El XML analizado se representa internamente mediante un árbol de objetos al que se puede acceder mediante las distintas clases de QDom. Todas las clases de QDom solo hacen referencia a objetos del árbol interno. Los objetos internos del árbol DOM se eliminarán una vez que se elimine el último objeto de QDom que haga referencia a ellos o el propio QDomDocument.
La creación de elementos, nodos de texto, etc., se realiza mediante las diversas funciones de fábrica que proporciona esta clase. El uso de los constructores predeterminados de las clases QDom solo dará como resultado objetos vacíos que no se pueden manipular ni insertar en el documento.
La clase QDomDocument dispone de varias funciones para crear datos del documento, por ejemplo: createElement(), createTextNode(), createComment(), createCDATASection(), createProcessingInstruction(), createAttribute() y createEntityReference(). Algunas de estas funciones tienen versiones compatibles con espacios de nombres, es decir, createElementNS() y createAttributeNS(). La función createDocumentFragment() se utiliza para almacenar partes del documento; esto resulta útil para manipular documentos complejos.
El contenido completo del documento se establece con ` setContent()`. Esta función analiza la cadena que se le pasa como documento XML y crea el árbol DOM que representa el documento. Se puede acceder al elemento raíz mediante ` documentElement()`. La representación textual del documento se puede obtener mediante ` toString()`.
Nota: El árbol DOM puede llegar a ocupar mucha memoria si el documento XML es grande. Para este tipo de documentos, la clase QXmlStreamReader podría ser una mejor solución.
Es posible insertar un nodo de otro documento en el documento mediante importNode().
Se puede obtener una lista de todos los elementos que tienen una etiqueta concreta mediante elementsByTagName() o elementsByTagNameNS().
Las clases QDom se suelen utilizar de la siguiente manera:
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);Una vez que doc y elem quedan fuera del ámbito, se elimina todo el árbol interno que representa el documento XML.
Para crear un documento utilizando el DOM, utiliza un código como este:
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();Para obtener más información sobre el Modelo de Objetos de Documento (DOM), consulta las Especificaciones Básicas del Modelo de Objetos de Documento (DOM) de Nivel 1 y Nivel 2.
Véase también la aplicación de marcadores DOM.
Documentación sobre los tipos de miembro
[since 6.5] enum class QDomDocument::ParseOption
flags QDomDocument::ParseOptions
Esta enumeración describe las opciones posibles que se pueden utilizar al analizar un documento XML mediante el método setContent().
| Constante | Valor | Descripción |
|---|---|---|
QDomDocument::ParseOption::Default | 0x00 | No se ha establecido ninguna opción de análisis. |
QDomDocument::ParseOption::UseNamespaceProcessing | 0x01 | El procesamiento de espacios de nombres está habilitado. |
QDomDocument::ParseOption::PreserveSpacingOnlyNodes | 0x02 | Se conservan los nodos de texto que solo contienen caracteres de espaciado. |
Esta enumeración se introdujo en Qt 6.5.
El tipo `ParseOptions` es una definición de tipo (typedef) para ` QFlags<ParseOption>`. Almacena una combinación OR de valores de `ParseOption`.
Véase también setContent().
Documentación de funciones miembro
QDomDocument::QDomDocument()
Crea un documento vacío.
[explicit] QDomDocument::QDomDocument(const QDomDocumentType &doctype)
Crea un documento con el tipo de documento « doctype ».
Véase también QDomImplementation::createDocumentType().
[explicit] QDomDocument::QDomDocument(const QString &name)
Crea un documento y establece el nombre del tipo de documento como « name ».
QDomDocument::QDomDocument(const QDomDocument &document)
Crea una copia de document.
Los datos de la copia son compartidos (copia superficial): al modificar un nodo, también se modificará el otro. Si deseas realizar una copia profunda, utiliza cloneNode().
[noexcept] QDomDocument::~QDomDocument()
Destruye el objeto y libera sus recursos.
QDomAttr QDomDocument::createAttribute(const QString &name)
Crea un nuevo atributo denominado « name » que se puede insertar en un elemento, por ejemplo, mediante la función ` QDomElement::setAttributeNode()`.
Si « name » no es un nombre XML válido, el comportamiento de esta función se rige por « QDomImplementation::InvalidDataPolicy ».
Véase también ` createAttributeNS()`.
QDomAttr QDomDocument::createAttributeNS(const QString &nsURI, const QString &qName)
Crea un nuevo atributo compatible con espacios de nombres que puede insertarse en un elemento. El nombre del atributo es qName y el URI del espacio de nombres es nsURI. Esta función también establece QDomNode::prefix() y QDomNode::localName() con los valores adecuados (en función de qName).
Si qName no es un nombre XML válido, el comportamiento de esta función se rige por QDomImplementation::InvalidDataPolicy.
Véase también createAttribute().
QDomCDATASection QDomDocument::createCDATASection(const QString &value)
Crea una nueva sección CDATA para la cadena « value », que puede insertarse en el documento, por ejemplo, mediante la función ` QDomNode::appendChild()`.
Si « value » contiene caracteres que no se pueden almacenar en una sección CDATA, el comportamiento de esta función se rige por « QDomImplementation::InvalidDataPolicy ».
Véanse también QDomNode::appendChild(), QDomNode::insertBefore() y QDomNode::insertAfter().
QDomComment QDomDocument::createComment(const QString &value)
Crea un nuevo comentario para la cadena « value » que se puede insertar en el documento, por ejemplo, utilizando ` QDomNode::appendChild()`.
Si value contiene caracteres que no se pueden almacenar en un comentario XML, el comportamiento de esta función se rige por QDomImplementation::InvalidDataPolicy.
Véase también QDomNode::appendChild(), QDomNode::insertBefore() y QDomNode::insertAfter().
QDomDocumentFragment QDomDocument::createDocumentFragment()
Crea un nuevo fragmento de documento, que puede utilizarse para almacenar partes del documento, por ejemplo, al realizar manipulaciones complejas del árbol del documento.
QDomElement QDomDocument::createElement(const QString &tagName)
Crea un nuevo elemento denominado « tagName » que se puede insertar en el árbol DOM, por ejemplo, mediante la función « QDomNode::appendChild()».
Si « tagName » no es un nombre XML válido, el comportamiento de esta función se rige por « QDomImplementation::InvalidDataPolicy ».
Véanse también createElementNS(), QDomNode::appendChild(), QDomNode::insertBefore() y QDomNode::insertAfter().
QDomElement QDomDocument::createElementNS(const QString &nsURI, const QString &qName)
Crea un nuevo elemento compatible con espacios de nombres que puede insertarse en el árbol DOM. El nombre del elemento es qName y el URI del espacio de nombres es nsURI. Esta función también establece QDomNode::prefix() y QDomNode::localName() en los valores adecuados (en función de qName).
Si qName es una cadena vacía, devuelve un elemento nulo independientemente de si está configurada la política de datos no válidos.
Véase también createElement().
QDomEntityReference QDomDocument::createEntityReference(const QString &name)
Crea una nueva referencia de entidad denominada « name » que se puede insertar en el documento, por ejemplo, mediante la función ` QDomNode::appendChild()`.
Si « name » no es un nombre XML válido, el comportamiento de esta función se rige por « QDomImplementation::InvalidDataPolicy ».
Véase también QDomNode::appendChild(), QDomNode::insertBefore() y QDomNode::insertAfter().
QDomProcessingInstruction QDomDocument::createProcessingInstruction(const QString &target, const QString &data)
Crea una nueva instrucción de procesamiento que se puede insertar en el documento, por ejemplo, mediante QDomNode::appendChild(). Esta función establece el destino de la instrucción de procesamiento en target y los datos en data.
Si target no es un nombre XML válido, o si «data» contiene caracteres que no pueden aparecer en una instrucción de procesamiento, el comportamiento de esta función se rige por QDomImplementation::InvalidDataPolicy.
Véanse también QDomNode::appendChild(), QDomNode::insertBefore() y QDomNode::insertAfter().
QDomText QDomDocument::createTextNode(const QString &value)
Crea un nodo de texto para la cadena « value » que se puede insertar en el árbol del documento, por ejemplo, utilizando la función ` QDomNode::appendChild()`.
Si « value » contiene caracteres que no pueden almacenarse como datos de caracteres de un documento XML (ni siquiera en forma de referencias de caracteres), el comportamiento de esta función se rige por « QDomImplementation::InvalidDataPolicy ».
Véanse también QDomNode::appendChild(), QDomNode::insertBefore() y QDomNode::insertAfter().
QDomDocumentType QDomDocument::doctype() const
Devuelve el tipo de este documento.
QDomElement QDomDocument::documentElement() const
Devuelve el elemento raíz del documento.
QDomElement QDomDocument::elementById(const QString &elementId)
Devuelve el elemento cuyo ID es igual a elementId. Si no se encuentra ningún elemento con ese ID, esta función devuelve un null element.
Dado que las clases QDomClasses no saben qué atributos son identificadores de elementos, esta función devuelve siempre un ` null element`. Esto podría cambiar en una versión futura.
QDomNodeList QDomDocument::elementsByTagName(const QString &tagname) const
Devuelve un objeto ` QDomNodeList` que contiene todos los elementos del documento con el nombre ` tagname`. El orden de la lista de nodos es el orden en que aparecen en un recorrido en preorden del árbol de elementos.
Véase también elementsByTagNameNS() y QDomElement::elementsByTagName().
QDomNodeList QDomDocument::elementsByTagNameNS(const QString &nsURI, const QString &localName)
Devuelve un objeto ` QDomNodeList ` que contiene todos los elementos del documento con el nombre local ` localName ` y un URI de espacio de nombres ` nsURI`. El orden de la lista de nodos es el orden en que aparecen en un recorrido en preorden del árbol de elementos.
Véase también elementsByTagName() y QDomElement::elementsByTagNameNS().
QDomImplementation QDomDocument::implementation() const
Devuelve un objeto ` QDomImplementation `.
QDomNode QDomDocument::importNode(const QDomNode &importedNode, bool deep)
Importa el nodo importedNode desde otro documento a este documento. importedNode permanece en el documento original; esta función crea una copia que se puede utilizar dentro de este documento.
Esta función devuelve el nodo importado que pertenece a este documento. El nodo devuelto no tiene padre. No es posible importar los nodos QDomDocument ni QDomDocumentType. En esos casos, esta función devuelve un null node.
Si importedNode es un null node, se devuelve un nodo nulo.
Si deep es verdadero, esta función importa no solo el nodo importedNode, sino todo su subárbol; si es falso, solo se importa el importedNode. El argumento deep no tiene ningún efecto sobre los nodos QDomAttr y QDomEntityReference, ya que los descendientes de los nodos QDomAttr siempre se importan y los de los nodos QDomEntityReference nunca se importan.
El comportamiento de esta función varía ligeramente en función de los tipos de nodo:
| Tipo de nodo | Comportamiento |
|---|---|
| QDomAttr | El elemento «owner» se establece en 0 y el indicador especificado se establece en «true» en el atributo generado. El subárbol completo de importedNode siempre se importa para los nodos de atributo: deep no tiene ningún efecto. |
| QDomDocument | Los nodos de documento no se pueden importar. |
| QDomDocumentFragment | Si deep es «true», esta función importa el fragmento de documento completo; en caso contrario, solo genera un fragmento de documento vacío. |
| QDomDocumentType | Los nodos de tipo documento no se pueden importar. |
| QDomElement | Los atributos para los que QDomAttr::specified() es verdadero también se importan; los demás atributos no se importan. Si deep es verdadero, esta función también importa el subárbol de importedNode; en caso contrario, solo importa el nodo de elemento (y algunos atributos, véase más arriba). |
| QDomEntity | Los nodos de entidad se pueden importar, pero por el momento no hay forma de utilizarlos, ya que el tipo de documento es de solo lectura en DOM nivel 2. |
| QDomEntityReference | Los descendientes de los nodos de referencia de entidad nunca se importan: deep no tiene ningún efecto. |
| QDomNotation | Los nodos de notación pueden importarse, pero por el momento no hay forma de utilizarlos, ya que el tipo de documento es de solo lectura en DOM nivel 2. |
| QDomProcessingInstruction | El destino y el valor de la instrucción de procesamiento se copian en el nuevo nodo. |
| QDomText | El texto se copia en el nuevo nodo. |
| QDomCDATASection | El texto se copia al nuevo nodo. |
| QDomComment | El texto se copia al nuevo nodo. |
Véase también QDomElement::setAttribute(), QDomNode::insertBefore(), QDomNode::insertAfter(), QDomNode::replaceChild(), QDomNode::removeChild() y QDomNode::appendChild().
QDomNode::NodeType QDomDocument::nodeType() const
Devuelve « DocumentNode ».
[since 6.5] QDomDocument::ParseResult QDomDocument::setContent(QAnyStringView text, 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)
Esta función analiza el documento XML a partir de la matriz de bytes data, la vista de cadena text, el objeto IO device o el flujo reader, y lo establece como contenido del documento. Intenta detectar la codificación del documento, de acuerdo con la especificación XML. Devuelve el resultado del análisis en ParseResult, que se convierte explícitamente a bool.
Se puede utilizar el parámetro options para especificar diferentes opciones de análisis, por ejemplo, para habilitar el procesamiento de espacios de nombres, etc.
Por defecto, el procesamiento de espacios de nombres está desactivado. Si está desactivado, el analizador no realiza ningún procesamiento de espacios de nombres al leer el archivo XML. Las funciones QDomNode::prefix(), QDomNode::localName() y QDomNode::namespaceURI() devuelven una cadena vacía.
Si el procesamiento de espacios de nombres se habilita mediante la opción `parse options`, el analizador reconoce los espacios de nombres en el archivo XML y establece el nombre del prefijo, el nombre local y el URI del espacio de nombres con los valores adecuados. Las funciones ` QDomNode::prefix()`, ` QDomNode::localName()` y ` QDomNode::namespaceURI()` devuelven una cadena para todos los elementos y atributos, y devuelven una cadena vacía si el elemento o atributo no tiene prefijo.
Los nodos de texto que constan únicamente de espacios en blanco se eliminan y no aparecerán en QDomDocument. Desde Qt 6.5, se puede pasar QDomDocument::ParseOption::PreserveSpacingOnlyNodes como opción de análisis para especificar que se deben conservar los nodos de texto que solo contienen espacios.
Las referencias a entidades se tratan de la siguiente manera:
- Se incluyen las referencias a entidades generales internas y a entidades de caracteres que aparecen en el contenido. El resultado es un nodo ` QDomText ` en el que las referencias se sustituyen por sus valores de entidad correspondientes.
- Se incluyen las referencias a entidades de parámetro que aparecen en el subconjunto interno. El resultado es un nodo « QDomDocumentType » que contiene declaraciones de entidades y notaciones, con las referencias sustituidas por sus valores de entidad correspondientes.
- Cualquier referencia a una entidad analizada general que no esté definida en el subconjunto interno y que aparezca en el contenido se representa como un nodo QDomEntityReference.
- Cualquier referencia a una entidad analizada que no esté definida en el subconjunto interno y que aparezca fuera del contenido se sustituye por una cadena vacía.
- Cualquier referencia a entidad no analizada se sustituye por una cadena vacía.
Nota: La sobrecarga que toma un IO ` device ` intentará abrirlo en modo de solo lectura si aún no está abierto. En ese caso, el autor de la llamada es responsable de llamar a `close`. Esto cambiará en Qt 7, que ya no abrirá el IO ` device`. Por lo tanto, las aplicaciones deben abrir el dispositivo por sí mismas antes de llamar a ` setContent()`.
Estas funciones se introdujeron en Qt 6.5.
Véase también ParseResult y ParseOptions.
QByteArray QDomDocument::toByteArray(int indent = 1) const
Convierte el documento analizado de nuevo a su representación textual y devuelve un objeto ` QByteArray ` que contiene los datos codificados en UTF-8.
Esta función utiliza ` indent ` como valor para el espacio de sangría de los subelementos.
Véase también toString().
QString QDomDocument::toString(int indent = 1) const
Convierte el documento analizado de nuevo a su representación textual.
Esta función utiliza ` indent ` como valor para la sangría de los subelementos.
Si indent es -1, no se añade ningún espacio en blanco.
QDomDocument &QDomDocument::operator=(const QDomDocument &other)
Asigna ` other ` a este documento DOM.
Los datos de la copia se comparten (copia superficial): al modificar un nodo, también se modificará el otro. Si deseas realizar una copia profunda, utiliza cloneNode().
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.