QXmlStreamWriter Class
QXmlStreamWriter クラスは、シンプルなストリーミング API を備えた XML 1.0 ライターを提供します。詳細...
ヘッダ | #include <QXmlStreamWriter> |
CMake: | find_package(Qt6 REQUIRED COMPONENTS Core) target_link_libraries(mytarget PRIVATE Qt6::Core) |
qmake: | QT += core |
- 継承メンバを含む全メンバ一覧
- QXmlStreamWriterはXMLクラスの一部です。
注意:このクラスの関数はすべてリエントラントです。
パブリック型
(since 6.10) enum class | Error { None, IO, Encoding, InvalidCharacter, Custom } |
プロパティ
- autoFormatting : bool
- autoFormattingIndent : int
(since 6.10)
stopWritingOnError : bool
パブリック機能
QXmlStreamWriter() | |
QXmlStreamWriter(QByteArray *array) | |
QXmlStreamWriter(QIODevice *device) | |
QXmlStreamWriter(QString *string) | |
~QXmlStreamWriter() | |
bool | autoFormatting() const |
int | autoFormattingIndent() const |
QIODevice * | device() const |
(since 6.10) QXmlStreamWriter::Error | error() const |
(since 6.10) QString | errorString() const |
bool | hasError() const |
(since 6.10) void | raiseError(QAnyStringView message) |
void | setAutoFormatting(bool enable) |
void | setAutoFormattingIndent(int spacesOrTabs) |
void | setDevice(QIODevice *device) |
void | setStopWritingOnError(bool stop) |
bool | stopWritingOnError() const |
void | writeAttribute(QAnyStringView namespaceUri, QAnyStringView name, QAnyStringView value) |
void | writeAttribute(const QXmlStreamAttribute &attribute) |
void | writeAttribute(QAnyStringView qualifiedName, QAnyStringView value) |
void | writeAttributes(const QXmlStreamAttributes &attributes) |
void | writeCDATA(QAnyStringView text) |
void | writeCharacters(QAnyStringView text) |
void | writeComment(QAnyStringView text) |
void | writeCurrentToken(const QXmlStreamReader &reader) |
void | writeDTD(QAnyStringView dtd) |
void | writeDefaultNamespace(QAnyStringView namespaceUri) |
void | writeEmptyElement(QAnyStringView namespaceUri, QAnyStringView name) |
void | writeEmptyElement(QAnyStringView qualifiedName) |
void | writeEndDocument() |
void | writeEndElement() |
void | writeEntityReference(QAnyStringView name) |
void | writeNamespace(QAnyStringView namespaceUri, QAnyStringView prefix = {}) |
void | writeProcessingInstruction(QAnyStringView target, QAnyStringView data = {}) |
void | writeStartDocument(QAnyStringView version) |
void | writeStartDocument(QAnyStringView version, bool standalone) |
void | writeStartDocument() |
void | writeStartElement(QAnyStringView namespaceUri, QAnyStringView name) |
void | writeStartElement(QAnyStringView qualifiedName) |
void | writeTextElement(QAnyStringView namespaceUri, QAnyStringView name, QAnyStringView text) |
void | writeTextElement(QAnyStringView qualifiedName, QAnyStringView text) |
詳細説明
QXmlStreamWriter は、QXmlStreamReader と対になる XML 書き込み関数です。XML 1.0 仕様に準拠しており、XML 1.0 構文、エスケープ規則、文字有効性制約を使用してドキュメントを記述します。
注: XML 1.1には対応していない。バージョン文字列は出力に手動で設定することができますが、追加の制御文字など XML 1.1 固有の機能を必要とするドキュメントは、このクラスを使用して作成することはできません。
関連クラスと同様、setDevice() で指定されたQIODevice を操作します。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データを自動的にフォーマットすることができます。この機能は、autoFormatting プロパティでオンにすることができ、autoFormattingIndent プロパティでカスタマイズすることができます。
その他の関数として、writeCDATA ()、writeComment ()、writeProcessingInstruction ()、writeDTD ()がある。XML ストリームの連結は、writeCurrentToken() でサポートされています。
QXmlStreamWriter は、常に XML を UTF-8 でエンコードします。
書き込み中にエラーが発生した場合、hasError() は真を返します。ただし、既定では、エラーが発生した時点で既にバッファリングされていたデータ、または同じ操作内から書き込まれたデータは、まだ基礎となるデバイスに書き込まれる可能性があります。これは、Error::Encoding 、Error::InvalidCharacter 、およびユーザが起動したError::Custom に適用される。これを回避し、エラー後にデータが書き込まれないようにするには、stopWritingOnError プロパティを使用します。このプロパティを有効にすると、最初のエラーは即座に出力を停止し、ライタ はそれ以降のすべての書き込み操作を無視する。アプリケーションは、エラー状態をターミナルとして扱い、エラー後のライターのさらなる使用を避ける必要があります。
QXmlStream Bookmarks の例では、ストリーム・ライターを使用して、QXmlStreamReader によって以前に読み込まれた XML ブックマーク・ファイル (XBEL) を書き込む方法を示します。
メンバ型ドキュメント
[since 6.10]
enum class QXmlStreamWriter::Error
この列挙型は、QXmlStreamWriter で XML を記述する際に発生する可能性のある、さまざまなエラーケースを指定します。
定数 | 値 | 説明 |
---|---|---|
QXmlStreamWriter::Error::None | 0 | エラーは発生していない。 |
QXmlStreamWriter::Error::IO | 1 | デバイスへの書き込み中に I/O エラーが発生しました。 |
QXmlStreamWriter::Error::Encoding | 2 | 出力フォーマットへの文字変換中にエンコーディング・エラーが発生しました。 |
QXmlStreamWriter::Error::InvalidCharacter | 3 | XML 1.0 で許可されていない文字が書き込み中に発生しました。 |
QXmlStreamWriter::Error::Custom | 4 | raiseError() でカスタムエラーが発生しました。 |
この enum は Qt 6.10 で導入されました。
プロパティのドキュメント
autoFormatting : bool
このプロパティは、ストリーム・ライターの自動フォーマット・フラグを保持する。
このプロパティは、ストリーム・ライターが生成された XML データを自動的にフォーマットするかどうかを制御します。有効な場合、ライターは要素間の空白部分 (無視可能な空白) に改行とインデントを自動的に追加します。自動書式の主な目的は、データを複数の行に分割し、人間が読む際の可読性を高めることです。インデントの深さは、autoFormattingIndent プロパティで制御できます。
デフォルトでは、オートフォーマットは無効になっています。
アクセス関数:
bool | autoFormatting() const |
void | setAutoFormatting(bool enable) |
autoFormattingIndent : int
このプロパティは、自動書式設定が有効な場合にインデントに使用されるスペースまたはタブの数を保持する。正の数はスペースを示し、負の数はタブを示す。
デフォルトのインデントは4です。
アクセス関数:
int | autoFormattingIndent() const |
void | setAutoFormattingIndent(int spacesOrTabs) |
autoFormattingも参照してください 。
[since 6.10]
stopWritingOnError : bool
このプロパティは、エラー発生後にデバイスへの書き込みを停止するオプションを保持する。
このプロパティがtrue
に設定されている場合、ライタはエラーに遭遇すると即座に書き込みを停止し、それ以降のすべての書き込み操作を無視する。このプロパティがfalse
に設定されている場合、ライタはエラー発生後も書き込みを続行することができ、無効な書き込みはスキップされるが、それ以降の出力は許可される。
これにはError::InvalidCharacter 、Error::Encoding 、Error::Custom が含まれることに注意。Error::IO は常に終端とみなされ、この設定に関係なく書き込みを停止する。
デフォルト値はfalse
です。
このプロパティは Qt 6.10 で導入されました。
アクセス関数:
bool | stopWritingOnError() const |
void | setStopWritingOnError(bool stop) |
メンバ関数のドキュメント
QXmlStreamWriter::QXmlStreamWriter()
ストリーム・ライターを構築します。
setDevice()も参照してください 。
[explicit]
QXmlStreamWriter::QXmlStreamWriter(QByteArray *array)
array に書き込むストリーム・ライターを構築する。これは、QBuffer デバイス上で動作し、array で動作するxmlライターを作成するのと同じである。
[explicit]
QXmlStreamWriter::QXmlStreamWriter(QIODevice *device)
device に書き込むストリーム・ライターを構築します;
[explicit]
QXmlStreamWriter::QXmlStreamWriter(QString *string)
string に書き込むストリーム・ライターを構築します。
[noexcept]
QXmlStreamWriter::~QXmlStreamWriter()
破壊者。
bool QXmlStreamWriter::autoFormatting() const
自動書式設定が有効であればtrue
を返し、そうでなければfalse
を返す。
メモ: プロパティ autoFormatting のゲッター関数。
setAutoFormatting()も参照してください 。
QIODevice *QXmlStreamWriter::device() const
QXmlStreamWriterデバイスが割り当てられていない場合はnullptr
を返す。
setDevice()も参照のこと 。
[since 6.10]
QXmlStreamWriter::Error QXmlStreamWriter::error() const
ライターの現在のエラー状態を返す。
エラーが発生していない場合、この関数はQXmlStreamWriter::Error::None を返します。
この関数は Qt 6.10 で導入されました。
errorString(), raiseError(const QString &message),hasError()も参照してください 。
[since 6.10]
QString QXmlStreamWriter::errorString() const
エラーが発生した場合、関連するエラーメッセージを返す。
エラー・メッセージは、QXmlStreamWriter によって内部的に設定されるか、raiseError() を介してユーザーによって提供される。エラーが発生していない場合、この関数はNULL文字列を返します。
この関数は Qt 6.10 で導入されました。
error(), raiseError(const QString &message),hasError()も参照してください 。
bool QXmlStreamWriter::hasError() const
データを書き込もうとしてエラーが発生した場合、true
を返す。
エラーがError::IO の場合、それ以降のQIODevice への書き込みは失敗する。その他の場合、不正なデータがドキュメントに書き込まれるかもしれない。
エラー・ステータスは決してリセットされない。エラー発生後に行われた書き込みは、エラー状態が解除されても無視されることがある。
error(),errorString(), raiseError(const QString &message)も参照のこと 。
[since 6.10]
void QXmlStreamWriter::raiseError(QAnyStringView message)
与えられたmessage でカスタムエラーを発生させる。
この関数は、アプリケーションレベルの検証失敗のような、書き込み中にエラーが発生したことを手動で表示するためのものです。
この関数は Qt 6.10 で導入されました。
errorString(),error(),hasError()も参照してください 。
void QXmlStreamWriter::setAutoFormatting(bool enable)
enable がtrue
の場合は自動組版を有効にし、それ以外の場合は無効にする。
デフォルト値はfalse
です。
備考: プロパティautoFormatting に対するセッター関数。
autoFormatting()も参照してください 。
void QXmlStreamWriter::setDevice(QIODevice *device)
現在のデバイスをdevice に設定する。 ストリームをQByteArray に書き込みたい場合は、QBuffer デバイスを作成する。
device()も参照のこと 。
void QXmlStreamWriter::writeAttribute(QAnyStringView namespaceUri, QAnyStringView name, QAnyStringView value)
指定されたnamespaceUri の前にname とvalue を付けた属性を書き込みます。名前空間がまだ宣言されていない場合、QXmlStreamWriter が名前空間宣言を生成します。
この関数は、コンテンツが書き込まれる前のwriteStartElement() の後、またはwriteEmptyElement() の後にのみ呼び出すことができます。
注意: Qt 6.5 より前のバージョンでは、この関数はQAnyStringView ではなくQString を呼び出します。
void QXmlStreamWriter::writeAttribute(const QXmlStreamAttribute &attribute)
attribute を書き込む。
この関数は、コンテンツが書き込まれる前のwriteStartElement() の後、またはwriteEmptyElement() の後にのみ呼び出すことができる。
これはオーバーロードされた関数である。
void QXmlStreamWriter::writeAttribute(QAnyStringView qualifiedName, QAnyStringView value)
qualifiedName とvalue で属性を書き込む。
この関数は、コンテンツが書き込まれる前のwriteStartElement() の後、またはwriteEmptyElement() の後にのみ呼び出すことができます。
注意: Qt 6.5 より前のバージョンでは、この関数はQAnyStringView ではなくQString を呼び出します。
これはオーバーロードされた関数です。
void QXmlStreamWriter::writeAttributes(const QXmlStreamAttributes &attributes)
属性ベクトルattributes を書き込みます。属性で参照される名前空間がまだ宣言されていない場合、QXmlStreamWriter はそのための名前空間宣言を生成します。
この関数は、内容が書き込まれる前のwriteStartElement() の後、またはwriteEmptyElement() の後にのみ呼び出すことができます。
writeAttribute() およびwriteNamespace()も参照 。
void QXmlStreamWriter::writeCDATA(QAnyStringView text)
text をCDATAセクションとして書き込む。text に禁じられた文字列 "]]> が含まれる場合、異なる CDATA セクションに分割される。
この関数は主に補完のために存在する。writeCharacters() は、コンテンツ以外の文字を自動的にエスケープするので、通常は使用する必要はありません。
注意: Qt 6.5 より前のバージョンでは、この関数はQAnyStringView ではなくQString を取っていました。
void QXmlStreamWriter::writeCharacters(QAnyStringView text)
text を書き込む。文字「<」、「&」、「""」は、実体参照「<」、「&」、「"」としてエスケープされる。禁じられた文字列"]]>"を避けるために、">"は"> "としてエスケープされます。
注意: Qt 6.5より前のバージョンでは、この関数はQAnyStringView ではなくQString を取っていました。
writeEntityReference()も参照してください 。
void QXmlStreamWriter::writeComment(QAnyStringView text)
text をXMLのコメントとして書き込む。text は、禁じられたシーケンス--
を含んではならないし、-
で終わってはならない。XMLはコメントで-
をエスケープする方法を提供しないことに注意してください。
注意: Qt 6.5 より前のバージョンでは、この関数はQAnyStringView ではなくQString を取っていました。
void QXmlStreamWriter::writeCurrentToken(const QXmlStreamReader &reader)
reader の現在の状態を書き込む。 有効な状態はすべてサポートされている。
この関数の目的は、XMLデータの連鎖処理をサポートすることである。
QXmlStreamReader::tokenType()も参照のこと 。
void QXmlStreamWriter::writeDTD(QAnyStringView dtd)
DTDセクションを書き込む。dtd はXML 1.0仕様のdoctypedeclプロダクション全体を表します。
注意: Qt 6.5より前のバージョンでは、この関数はQAnyStringView ではなくQString を取っていました。
void QXmlStreamWriter::writeDefaultNamespace(QAnyStringView namespaceUri)
namespaceUri のデフォルト名前空間宣言を書き込みます。
writeStartElement() またはwriteEmptyElement() が呼び出された場合、宣言は現在の要素に適用されます。
http://www.w3.org/XML/1998/namespace(xmlns にバインド) とhttp://www.w3.org/2000/xmlns/(xml にバインド) の名前空間は、定義上デフォルトとして宣言できないことに注意してください。
注意: Qt 6.5 より前のバージョンでは、この関数はQAnyStringView ではなくQString を取っていました。
void QXmlStreamWriter::writeEmptyElement(QAnyStringView namespaceUri, QAnyStringView name)
指定されたnamespaceUri の前にname を付けた空の要素を書き込みます。名前空間が宣言されていない場合、QXmlStreamWriter が名前空間宣言を生成します。その後にwriteAttribute() を呼び出すと、この要素に属性が追加されます。
注意: Qt 6.5 より前のバージョンでは、この関数はQAnyStringView ではなくQString を呼び出します。
writeNamespace()も参照してください 。
void QXmlStreamWriter::writeEmptyElement(QAnyStringView qualifiedName)
qualifiedName という修飾名を持つ空の要素を書き込みます。その後writeAttribute() を呼び出すと、この要素に属性が追加されます。
注意: Qt 6.5 より前のバージョンでは、この関数はQAnyStringView ではなくQString を取っていました。
これはオーバーロードされた関数です。
void QXmlStreamWriter::writeEndDocument()
開いている残りの開始要素をすべて閉じ、改行を書き込む。
writeStartDocument()も参照 。
void QXmlStreamWriter::writeEndElement()
直前の開始要素を閉じる。
writeStartElement()も参照 。
void QXmlStreamWriter::writeEntityReference(QAnyStringView name)
エンティティ参照name を "&name;" としてストリームに書き込みます。
注意: Qt 6.5 より前のバージョンでは、この関数はQAnyStringView ではなくQString を取ります。
void QXmlStreamWriter::writeNamespace(QAnyStringView namespaceUri, QAnyStringView prefix = {})
prefix を使ってnamespaceUri の名前空間宣言を記述する。prefix が空の場合、QXmlStreamWriter は、文字 'n' と数字からなる一意な接頭辞を割り当てる。
writeStartElement() またはwriteEmptyElement() が呼ばれた場合、宣言は現在の要素に適用され、そうでない場合は次の子要素に適用されます。
接頭辞xml は、http://www.w3.org/XML/1998/namespace のために定義済みかつ予約済みであり、他の接頭辞と結合することはできないことに注意。接頭辞xmlnsとその URIhttp://www.w3.org/2000/xmlns/は名前空間機構そのものに使われるため、宣言では完全に禁止されています。
注意: Qt 6.5 より前のバージョンでは、この関数はQAnyStringView ではなくQString を取っていました。
void QXmlStreamWriter::writeProcessingInstruction(QAnyStringView target, QAnyStringView data = {})
target とdata で XML 処理命令を書き込みます。data は "?>" というシーケンスを含んではいけません。
注意: Qt 6.5 より前のバージョンでは、この関数はQAnyStringView ではなくQString を取ります。
void QXmlStreamWriter::writeStartDocument(QAnyStringView version)
XML のバージョン番号version で始まる文書を書き込みます。
注意: この関数はバージョン文字列を検証しないので、手動で設定することができます。ただし、QXmlStreamWriter は XML 1.0 しかサポートしていません。バージョン文字列を "1.0 "以外に設定しても、ライターの動作やエスケープ規則は変わりません。宣言されたバージョンと実際のコンテンツとの整合性を確保するのは、呼び出し側の責任です。
注意: Qt 6.5 より前のバージョンでは、この関数はQAnyStringView ではなくQString を取っていました。
writeEndDocument()も参照してください 。
void QXmlStreamWriter::writeStartDocument(QAnyStringView version, bool standalone)
XML バージョン番号version とスタンドアロン属性standalone を持つ文書の開始を書き込みます。
注: この関数はバージョン文字列を検証せず、手動で設定することができます。ただし、QXmlStreamWriter は XML 1.0 しかサポートしていません。バージョン文字列を "1.0 "以外に設定しても、ライターの動作やエスケープ規則は変わりません。宣言されたバージョンと実際のコンテンツとの整合性を確保するのは、呼び出し側の責任です。
注意: Qt 6.5 より前のバージョンでは、この関数はQAnyStringView ではなくQString を取っていました。
writeEndDocument()も参照してください 。
void QXmlStreamWriter::writeStartDocument()
XMLバージョン番号 "1.0 "で始まる文書を書き出す。
これはオーバーロードされた関数です。
writeEndDocument()も参照 。
void QXmlStreamWriter::writeStartElement(QAnyStringView namespaceUri, QAnyStringView name)
指定されたnamespaceUri の前にname を付けた開始要素を書きます。名前空間がまだ宣言されていない場合、QXmlStreamWriter が名前空間宣言を生成します。その後にwriteAttribute() を呼び出すと、この要素に属性が追加されます。
注意: Qt 6.5 より前のバージョンでは、この関数はQAnyStringView ではなくQString を呼び出します。
writeNamespace(),writeEndElement(),writeEmptyElement()も参照してください 。
void QXmlStreamWriter::writeStartElement(QAnyStringView qualifiedName)
開始要素をqualifiedName で書き込みます。その後writeAttribute() を呼び出すと、この要素に属性が追加されます。
注意: Qt 6.5 より前のバージョンでは、この関数はQAnyStringView ではなくQString を受け取っていました。
これはオーバーロードされた関数です。
writeEndElement() およびwriteEmptyElement()も参照してください 。
void QXmlStreamWriter::writeTextElement(QAnyStringView namespaceUri, QAnyStringView name, QAnyStringView text)
name namespaceUri text名前空間が宣言されていない場合、QXmlStreamWriter が名前空間宣言を生成します。
と同等の便利な関数です:
writeStartElement(namespaceUri, name);
writeCharacters(text);
writeEndElement();
注意: Qt 6.5 より前のバージョンでは、この関数はQAnyStringView ではなくQString を受け取ります。
void QXmlStreamWriter::writeTextElement(QAnyStringView qualifiedName, QAnyStringView text)
text 要素をqualifiedName とtext で書き込む。
と同等の便利な関数です:
writeStartElement(qualifiedName); writeCharacters(text); writeEndElement();
注意: Qt 6.5 より前のバージョンでは、この関数はQAnyStringView ではなくQString を取っていました。
これはオーバーロードされた関数です。
© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.