Класс QXmlStreamWriter

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

Этот класс был представлен в Qt 4.3.

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

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

Свойства

• 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. Различные кодировки можно установить с помощью setCodec().

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

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

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

QXmlStreamWriter::QXmlStreamWriter(QString *string)

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

Обратите внимание, что при записи в QString, QXmlStreamWriter игнорирует кодировку, установленную с помощью setCodec(). См. эту функцию для получения дополнительной информации.

QXmlStreamWriter::QXmlStreamWriter(QByteArray *array)

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

QXmlStreamWriter::QXmlStreamWriter(QIODevice *device)

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

QXmlStreamWriter::QXmlStreamWriter()

Создаёт записыватель потока.

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

QXmlStreamWriter::~QXmlStreamWriter()

Деструктор.

bool QXmlStreamWriter::autoFormatting() const

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

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

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

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

QTextCodec *QXmlStreamWriter::codec() const

Возвращает кодировку, которая в данный момент назначена потоку.

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

QIODevice *QXmlStreamWriter::device() const

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

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

bool QXmlStreamWriter::hasError() const

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

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

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

void QXmlStreamWriter::setAutoFormatting(bool enable)

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

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

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

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

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

void QXmlStreamWriter::setCodec(QTextCodec *codec)

Устанавливает кодировку для этого потока в codec. Кодировка используется для кодирования любых данных, которые записываются. По умолчанию QXmlStreamWriter использует UTF-8.

Информация о кодировке хранится в начальном теге XML, который записывается при вызове writeStartDocument(). Вызовите эту функцию перед вызовом writeStartDocument().

Примечание: При записи XML в QString информация о кодировке игнорируется, и заголовок XML не будет содержать никакой информации о кодировке, так как все QStrings являются UTF-16. Если вы позже конвертируете QString в 8-битный формат, вам необходимо организовать передачу информации о кодировке вне потока.

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

void QXmlStreamWriter::setCodec(const char *codecName)

Устанавливает кодировку для этого потока в QTextCodec для кодировки, заданной codecName. Общие значения для codecName включают "ISO 8859-1", "UTF-8" и "UTF-16". Если кодировка не распознаётся, ничего не происходит.

Примечание: При записи XML в QString информация о кодировке игнорируется, и заголовок XML не будет содержать никакой информации о кодировке, так как все QStrings являются UTF-16. Если вы позже конвертируете QString в 8-битный формат, вам необходимо организовать передачу информации о кодировке вне потока.

См. также QTextCodec::codecForName().

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". Также записывает информацию об кодировке.

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

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

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

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

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

См. также 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();