Класс QXmlStreamWriter

Класс QXmlStreamWriter предоставляет простой потоковый API для записи XML. Подробнее...

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

Примечание: Все функции в этом классе являются реентерабельными.

Свойства

• autoFormatting : bool
• autoFormattingIndent : int

Открытые функции

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

QXmlStreamWriter является аналогом QXmlStreamReader для записи XML. Как и родственный класс, он работает с QIODevice, указанным с помощью setDevice(). API простой и понятный: для каждого XML-токена или события, который вы хотите записать, писатель предоставляет специализированную функцию.

Вы начинаете документ с помощью writeStartDocument() и заканчиваете его с помощью writeEndDocument(). Это неявно закроет все оставшиеся открытые теги.

Теги элементов открываются с помощью writeStartElement(), за которым следуют writeAttribute() или writeAttributes(), содержимое элемента, а затем writeEndElement(). Более короткая форма writeEmptyElement() может использоваться для записи пустых элементов, за которыми следуют writeAttributes().

Содержимое элемента состоит из символов, ссылок на сущности или вложенных элементов. Оно записывается с помощью writeCharacters(), который также обрабатывает экранирование всех запрещенных символов и последовательностей символов, writeEntityReference() или последующих вызовов writeStartElement(). Удобный метод writeTextElement() может использоваться для записи конечных элементов, которые содержат только текст.

Следующий сокращенный фрагмент кода показывает основное использование класса для записи отформатированного XML с отступами:

    QXmlStreamWriter stream(&output);
    stream.setAutoFormatting(true);
    stream.writeStartDocument();
    ...
    stream.writeStartElement("bookmark");
    stream.writeAttribute("href", "http://qt-project.org/");
    stream.writeTextElement("title", "Qt Project");
    stream.writeEndElement(); // bookmark
    ...
    stream.writeEndDocument();

QXmlStreamWriter отвечает за добавление префиксов пространств имен, все, что вам нужно сделать, это указать namespaceUri при записи элементов или атрибутов. Если вы должны соответствовать определенным префиксам, вы можете принудить писатель использовать их, объявив пространства имен вручную с помощью writeNamespace() или writeDefaultNamespace(). В качестве альтернативы, вы можете обойти поддержку пространств имен писателя потока и использовать перегруженные методы, которые принимают квалифицированное имя. Пространство имен http://www.w3.org/XML/1998/namespace является неявным и сопоставляется с префиксом xml.

Писатель потока может автоматически форматировать сгенерированные данные XML, добавляя переносы строк и отступы к пустым разделам между элементами, делая данные XML более читабельными для человека и удобными для работы с большинством систем управления исходным кодом. Функция может быть включена с помощью свойства autoFormatting и настраиваться с помощью свойства autoFormattingIndent.

Другие функции — writeCDATA(), writeComment(), writeProcessingInstruction() и writeDTD(). Поддерживается объединение потоков XML с помощью writeCurrentToken().

QXmlStreamWriter всегда кодирует XML в UTF-8.

Если при записи в базовое устройство произошла ошибка, hasError() начинает возвращать true, а последующие записи игнорируются.

Пример QXmlStream Bookmarks Example демонстрирует, как использовать писателя потока для записи файла закладок XML (XBEL), который был ранее прочитан с помощью QXmlStreamReader.

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

QXmlStreamWriter::QXmlStreamWriter(QString *string)

Создает писателя потока, который записывает в string.

QXmlStreamWriter::QXmlStreamWriter(QByteArray *array)

Создает писателя потока, который записывает в array. Это то же самое, что создание писателя xml, работающего с устройством QBuffer, которое, в свою очередь, работает с array.

QXmlStreamWriter::QXmlStreamWriter(QIODevice *device)

Создает писателя потока, который записывает в device;

QXmlStreamWriter::QXmlStreamWriter()

Создает писателя потока.

См. также setDevice().

QXmlStreamWriter::~QXmlStreamWriter()

Деструктор.

bool QXmlStreamWriter::autoFormatting() const

Возвращает true если автоматическое форматирование включено, в противном случае false.

Примечание: Функция-получатель для свойства autoFormatting.

См. также setAutoFormatting().

QIODevice *QXmlStreamWriter::device() const

Возвращает текущее устройство, связанное с QXmlStreamWriter, или nullptr если устройство не было назначено.

См. также setDevice().

bool QXmlStreamWriter::hasError() const

Возвращает true если запись не удалась.

Это может произойти, если поток не смог записать в базовое устройство или если данные, которые необходимо записать, содержали недопустимые символы.

Статус ошибки никогда не сбрасывается. Записи, выполняемые после возникновения ошибки, могут быть проигнорированы, даже если состояние ошибки сброшено.

void QXmlStreamWriter::setAutoFormatting(bool enable)

Включает автоматическое форматирование, если enable равно true, в противном случае отключает его.

Значение по умолчанию — false.

Примечание: Функция-установитель для свойства autoFormatting.

См. также autoFormatting().

void QXmlStreamWriter::setDevice(QIODevice *device)

Устанавливает текущее устройство в device. Если вы хотите, чтобы поток записывал в QByteArray, вы можете создать устройство QBuffer.

См. также device().

void QXmlStreamWriter::writeAttribute(const QString &namespaceUri, const QString &name, const QString &value)

Записывает атрибут с name и value, префикс для указанного namespaceUri. Если пространство имен еще не объявлено, QXmlStreamWriter сгенерирует объявление пространства имен для него.

Эту функцию можно вызывать только после writeStartElement() перед записью любого содержимого или после writeEmptyElement().

void QXmlStreamWriter::writeAttribute(const QString &qualifiedName, const QString &value)

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

Записывает атрибут с qualifiedName и value.

Эту функцию можно вызывать только после writeStartElement() перед записью любого содержимого или после writeEmptyElement().

void QXmlStreamWriter::writeAttribute(const QXmlStreamAttribute &attribute)

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

Записывает attribute.

Эту функцию можно вызывать только после writeStartElement() перед записью любого содержимого или после writeEmptyElement().

void QXmlStreamWriter::writeAttributes(const QXmlStreamAttributes &attributes)

Записывает вектор атрибутов attributes. Если пространство имен, указанное в атрибуте, еще не объявлено, QXmlStreamWriter сгенерирует объявление пространства имен для него.

Эту функцию можно вызывать только после writeStartElement() перед записью любого содержимого или после writeEmptyElement().

См. также writeAttribute() и writeNamespace().

void QXmlStreamWriter::writeCDATA(const QString &text)

Записывает text как раздел CDATA. Если text содержит запрещенную последовательность символов "]]>", она разделяется на различные разделы CDATA.

Эта функция в основном существует для полноты. Обычно вам не нужно ее использовать, потому что writeCharacters() автоматически экранирует все несодержащие символы.

void QXmlStreamWriter::writeCharacters(const QString &text)

Записывает text. Символы "<", "&" и """ экранируются как сущности "&lt;", "&amp;" и "&quot;". Чтобы избежать запрещенной последовательности "]]>", ">" также экранируется как "&gt;".

См. также writeEntityReference().

void QXmlStreamWriter::writeComment(const QString &text)

Записывает text как комментарий XML, где text не должен содержать запрещенную последовательность "--" или заканчиваться "-". Обратите внимание, что XML не предоставляет никакого способа экранировать "-" в комментарии.

void QXmlStreamWriter::writeCurrentToken(const QXmlStreamReader &reader)

Записывает текущее состояние reader. Поддерживаются все возможные допустимые состояния.

Цель этой функции — поддержка цепочечной обработки данных XML.

См. также QXmlStreamReader::tokenType().

void QXmlStreamWriter::writeDTD(const QString &dtd)

Записывает раздел DTD. dtd представляет собой полное произведение doctypedecl из спецификации XML 1.0.

void QXmlStreamWriter::writeDefaultNamespace(const QString &namespaceUri)

Записывает объявление по умолчанию для пространства имен namespaceUri.

Если был вызван writeStartElement() или writeEmptyElement(), объявление применяется к текущему элементу; в противном случае оно применяется к следующему дочернему элементу.

Обратите внимание, что пространства имен http://www.w3.org/XML/1998/namespace (связанное с xmlns) и http://www.w3.org/2000/xmlns/ (связанное с xml) по определению не могут быть объявлены по умолчанию.

void QXmlStreamWriter::writeEmptyElement(const QString &namespaceUri, const QString &name)

Записывает пустой элемент с именем name, префикс которого указан для заданного namespaceUri. Если пространство имен не объявлено, QXmlStreamWriter сгенерирует объявление пространства имен для него. Последующие вызовы writeAttribute() будут добавлять атрибуты к этому элементу.

См. также writeNamespace().

void QXmlStreamWriter::writeEmptyElement(const QString &qualifiedName)

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

Записывает пустой элемент с полным именем qualifiedName. Последующие вызовы writeAttribute() будут добавлять атрибуты к этому элементу.

void QXmlStreamWriter::writeEndDocument()

Закрывает все оставшиеся открытые начальные элементы и записывает новую строку.

См. также writeStartDocument().

void QXmlStreamWriter::writeEndElement()

Закрывает предыдущий начальный элемент.

См. также writeStartElement().

void QXmlStreamWriter::writeEntityReference(const QString &name)

Записывает ссылку на сущность name в поток как "&name;".

void QXmlStreamWriter::writeNamespace(const QString &namespaceUri, const QString &prefix = QString())

Записывает объявление пространства имен для namespaceUri с prefix. Если prefix пустое, QXmlStreamWriter присваивает уникальный префикс, состоящий из буквы 'n' и числа.

Если был вызван writeStartElement() или writeEmptyElement(), объявление применяется к текущему элементу; в противном случае оно применяется к следующему дочернему элементу.

Обратите внимание, что префикс xml предопределён и зарезервирован для http://www.w3.org/XML/1998/namespace, который в свою очередь не может быть привязан к какому-либо другому префиксу. Префикс xmlns и его URI http://www.w3.org/2000/xmlns/ используются для самого механизма пространства имен и поэтому полностью запрещены в объявлениях.

void QXmlStreamWriter::writeProcessingInstruction(const QString &target, const QString &data = QString())

Записывает инструкцию обработки XML с target и data, где data не должна содержать последовательность "?>".

void QXmlStreamWriter::writeStartDocument(const QString &version)

Записывает начало документа с номером версии XML version.

См. также writeEndDocument().

void QXmlStreamWriter::writeStartDocument()

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

Записывает начало документа с номером версии XML "1.0".

См. также writeEndDocument().

void QXmlStreamWriter::writeStartDocument(const QString &version, bool standalone)

Записывает начало документа с номером версии XML version и атрибутом standalone.

См. также writeEndDocument().

void QXmlStreamWriter::writeStartElement(const QString &namespaceUri, const QString &name)

Записывает начальный элемент с именем name, префикс которого указан для заданного namespaceUri. Если пространство имен ещё не объявлено, QXmlStreamWriter сгенерирует объявление пространства имен для него. Последующие вызовы writeAttribute() будут добавлять атрибуты к этому элементу.

См. также writeNamespace(), writeEndElement() и writeEmptyElement().

void QXmlStreamWriter::writeStartElement(const QString &qualifiedName)

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

Записывает начальный элемент с полным именем qualifiedName. Последующие вызовы writeAttribute() будут добавлять атрибуты к этому элементу.

См. также writeEndElement() и writeEmptyElement().

void QXmlStreamWriter::writeTextElement(const QString &namespaceUri, const QString &name, const QString &text)

Записывает текстовый элемент с именем name, префикс которого указан для заданного namespaceUri, и текстом text. Если пространство имен не объявлено, QXmlStreamWriter сгенерирует объявление пространства имен для него.

Это вспомогательная функция, эквивалентная:

        writeStartElement(namespaceUri, name);
        writeCharacters(text);
        writeEndElement();

void QXmlStreamWriter::writeTextElement(const QString &qualifiedName, const QString &text)

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

Записывает текстовый элемент с полным именем qualifiedName и текстом text.

Это вспомогательная функция, эквивалентная:

        writeStartElement(qualifiedName);
        writeCharacters(text);
        writeEndElement();