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

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

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

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

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

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

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