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

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

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

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

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