Класс QDomDocument

Класс QDomDocument представляет собой XML-документ. Подробнее...

• Список всех членов, включая унаследованные

Примечание: Все функции в этом классе являются повторно-входными за исключением следующих:

• setContent(const QByteArray &data, bool namespaceProcessing, QString *errorMsg, int *errorLine, int *errorColumn)

Публичные функции

• 65 публичных функций, унаследованных от QDomNode

Подробное описание

Класс QDomDocument представляет собой XML-документ.

Класс QDomDocument представляет собой весь XML-документ. По сути, он является корнем дерева документа и предоставляет основной доступ к данным документа.

Поскольку элементы, текстовые узлы, комментарии, инструкции обработки и т. д. не могут существовать вне контекста документа, класс документа также содержит функции-фабрики, необходимые для создания этих объектов. Объекты узлов, созданные таким образом, имеют функцию ownerDocument(), которая связывает их с документом, в контексте которого они были созданы. Классы DOM, которые будут чаще всего использоваться, это QDomNode, QDomDocument, QDomElement и QDomText.

Разложенный XML представлен внутренне деревом объектов, к которым можно получить доступ с помощью различных классов QDom. Все классы QDom только ссылаются на объекты во внутреннем дереве. Внутренние объекты в дереве 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()) << endl; // 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 и elem выйдут из области видимости, всё внутреннее дерево, представляющее XML-документ, удалится.

Для создания документа с помощью DOM используйте код подобный этому:

QDomDocument doc("MyML");
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) Level 1 и Level 2 Core.

См. также Пример DOM Bookmarks и Пример Simple DOM Model.

Документация по членам-функциям

QDomDocument::QDomDocument()

Создаёт пустой документ.

QDomDocument::QDomDocument(const QString &name)

Создаёт документ и устанавливает имя типа документа в name.

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 пустая строка, возвращает нулевой элемент, независимо от политики обработки неверных данных.

См. также 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, или data содержит символы, которые не могут появляться в инструкции обработки, поведение этой функции определяется 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)

Возвращает элемент, идентификатор которого равен elementId. Если элемент с заданным идентификатором не найден, эта функция возвращает нулевой элемент.

Так как классы QDom не знают, какие атрибуты являются идентификаторами элементов, эта функция всегда возвращает нулевой элемент. Это может измениться в будущей версии.

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::implementation() const

Возвращает объект QDomImplementation.

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

Импортирует узел importedNode из другого документа в текущий документ. Узел importedNode остаётся в исходном документе; эта функция создаёт копию, которую можно использовать внутри текущего документа.

Функция возвращает импортированный узел, принадлежащий текущему документу. Возвращённый узел не имеет родителя. Невозможно импортировать узлы QDomDocument и QDomDocumentType. В этих случаях функция возвращает нулевой узел.

Если importedNode является нулевым узлом, возвращается нулевой узел.

Если deep равно true, функция импортирует не только узел importedNode, но и всё его поддерево; если false, импортируется только сам узел importedNode. Аргумент deep не влияет на узлы QDomAttr и QDomEntityReference, так как потомки узлов QDomAttr всегда импортируются, а потомки узлов QDomEntityReference никогда не импортируются.

Поведение этой функции немного отличается в зависимости от типа узла:

См. также QDomElement::setAttribute(), QDomNode::insertBefore(), QDomNode::insertAfter(), QDomNode::replaceChild(), QDomNode::removeChild(), и QDomNode::appendChild().

QDomNode::NodeType QDomDocument::nodeType() const

Возвращает DocumentNode.

bool QDomDocument::setContent(const QByteArray &data, bool namespaceProcessing, QString *errorMsg = Q_NULLPTR, int *errorLine = Q_NULLPTR, int *errorColumn = Q_NULLPTR)

Эта функция анализирует XML-документ из массива байтов data и устанавливает его в качестве содержимого документа. Она пытается определить кодировку документа в соответствии со спецификацией XML.

Если namespaceProcessing равно true, анализатор распознаёт пространства имён в XML-файле и устанавливает имя префикса, локальное имя и URI пространства имён соответствующим значениям. Если namespaceProcessing равно false, анализатор не обрабатывает пространства имён при чтении XML-файла.

Если произошла ошибка анализа, эта функция возвращает false и сообщение об ошибке помещается в *errorMsg, номер строки в *errorLine и номер столбца в *errorColumn (если соответствующий указатель не равен 0); в противном случае эта функция возвращает true. Различные сообщения об ошибках описаны в документации класса QXmlParseException. Обратите внимание, что если вы хотите отобразить эти сообщения об ошибках пользователям вашего приложения, они будут отображаться на английском языке, если они явно не переведены.

Если namespaceProcessing равно true, функция QDomNode::prefix() возвращает строку для всех элементов и атрибутов. Она возвращает пустую строку, если у элемента или атрибута нет префикса.

Узлы текста, состоящие только из пробелов, удаляются и не будут отображаться в QDomDocument. Если это поведение нежелательно, можно использовать перегрузку setContent(), которая позволяет указать QXmlReader.

Если namespaceProcessing равно false, функции QDomNode::prefix(), QDomNode::localName() и QDomNode::namespaceURI() возвращают пустую строку.

Обработка ссылок на сущности происходит следующим образом:

• Ссылки на внутренние общие сущности и символьные сущности, встречающиеся в содержимом, включаются. Результатом является узел QDomText со ссылками, заменёнными соответствующими значениями сущностей.
• Ссылки на параметрические сущности, встречающиеся во внутреннем подмножестве, включаются. Результатом является узел QDomDocumentType, который содержит объявления сущностей и обозначений со ссылками, заменёнными соответствующими значениями сущностей.
• Любая общая ссылка на проанализированную сущность, которая не определена во внутреннем подмножестве и встречается в содержимом, представляется узлом QDomEntityReference.
• Любая ссылка на проанализированную сущность, которая не определена во внутреннем подмножестве и встречается вне содержимого, заменяется пустой строкой.
• Любая непроанализированная ссылка на сущность заменяется пустой строкой.

Предупреждение: Эта функция не является повторно входящей.

См. также QDomNode::namespaceURI(), QDomNode::localName(), QDomNode::prefix(), QString::isNull(), и QString::isEmpty().

bool QDomDocument::setContent(const QString &text, bool namespaceProcessing, QString *errorMsg = Q_NULLPTR, int *errorLine = Q_NULLPTR, int *errorColumn = Q_NULLPTR)

Это перегруженная функция.

Эта функция считывает XML-документ из строки text, возвращая true, если содержимое было успешно проанализировано; в противном случае возвращает false. Поскольку text уже является строкой Юникода, обнаружение кодировки не выполняется.

bool QDomDocument::setContent(QIODevice *dev, bool namespaceProcessing, QString *errorMsg = Q_NULLPTR, int *errorLine = Q_NULLPTR, int *errorColumn = Q_NULLPTR)

Это перегруженная функция.

Эта функция считывает XML-документ из устройства ввода-вывода dev, возвращая true, если содержимое было успешно распарсено; в противном случае возвращает false.

bool QDomDocument::setContent(QXmlInputSource *source, bool namespaceProcessing, QString *errorMsg = Q_NULLPTR, int *errorLine = Q_NULLPTR, int *errorColumn = Q_NULLPTR)

Это перегруженная функция.

Эта функция считывает XML-документ из QXmlInputSource source, возвращая true, если содержимое было успешно распарсено; в противном случае возвращает false.

Эта функция была добавлена в Qt 4.5.

bool QDomDocument::setContent(const QByteArray &buffer, QString *errorMsg = Q_NULLPTR, int *errorLine = Q_NULLPTR, int *errorColumn = Q_NULLPTR)

Это перегруженная функция.

Эта функция считывает XML-документ из массива байтов buffer, возвращая true, если содержимое было успешно распарсено; в противном случае возвращает false.

Обработка пространств имён не выполняется.

bool QDomDocument::setContent(const QString &text, QString *errorMsg = Q_NULLPTR, int *errorLine = Q_NULLPTR, int *errorColumn = Q_NULLPTR)

Это перегруженная функция.

Эта функция считывает XML-документ из строки text, возвращая true, если содержимое было успешно распарсено; в противном случае возвращает false. Поскольку text уже является строкой Юникод, обнаружение кодировки не выполняется.

Обработка пространств имён также не выполняется.

bool QDomDocument::setContent(QIODevice *dev, QString *errorMsg = Q_NULLPTR, int *errorLine = Q_NULLPTR, int *errorColumn = Q_NULLPTR)

Это перегруженная функция.

Эта функция считывает XML-документ из устройства ввода-вывода dev, возвращая true, если содержимое было успешно распарсено; в противном случае возвращает false.

Обработка пространств имён не выполняется.

bool QDomDocument::setContent(QXmlInputSource *source, QXmlReader *reader, QString *errorMsg = Q_NULLPTR, int *errorLine = Q_NULLPTR, int *errorColumn = Q_NULLPTR)

Это перегруженная функция.

Эта функция считывает XML-документ из QXmlInputSource source и анализирует его с помощью QXmlReader reader, возвращая true, если содержимое было успешно распарсено; в противном случае возвращает false.

Функция не изменяет параметры reader. Если вы хотите использовать определённые параметры для анализа, вы можете соответствующим образом настроить reader с помощью этой функции.

См. также QXmlSimpleReader.

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().