Класс QXmlStreamWriter

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

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

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

Свойства

• 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();