Класс 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();