qmlformat

qmlformat は、QML コーディング規約に従って QML ファイルの書式を自動的に整えるツールです。

オプションと設定

qmlformat はコマンドラインオプションで設定できます。オプションには、書式設定に直接関係するものと、ツールの動作を制御するものという 2 つのグループがあります。

以下のオプションは、ツールの動作にのみ影響します：

次のオプション群は、ファイルのフォーマット方法を制御するものであり、設定ファイルを介して制御することも可能です。

ブール値のオプションについては、コマンドラインでフラグを指定するか、設定ファイル内で変数を `true ` に設定することで、その動作を有効にします。

引数

使用方法

qmlformatは柔軟性が高く、ニーズに応じて設定を変更できます。信頼できないコード上で実行する場合（例えば、パブリック CI でのテスト中に QML ファイルのフォーマットを行う場合など）、qmlformat はサンドボックス、コンテナ、またはその他の安全な環境でデプロイする必要があります。

出力

qmlformat は、フォーマット済みのファイルを stdout に出力します。ファイルをその場で更新するには、-i フラグを指定してください。

プロパティ、関数、シグナルのグループ化

-n または--normalize フラグを指定すると、qmlformat は既存の順序を維持するのではなく、すべてのプロパティ、関数、シグナルを名前順にグループ化して並べ替えます。

例：

import QtQuick

QtObject {
    signal s2()
    property int h
    function z() {}
    property int w
    function y() {}
    id: asdf
    signal s1()

    property Item myItem2: Item {
        TextEdit {}
        Rectangle {}
    }
    property Item myItem: Item {
        Rectangle {}
        TextEdit {}
    }
}

は次のようにフォーマットされます：

import QtQuick

QtObject {
    id: asdf

    property int h
    property Item myItem: Item {
        Rectangle {
        }
        TextEdit {
        }
    }
    property Item myItem2: Item {
        TextEdit {
        }
        Rectangle {
        }
    }
    property int w

    signal s1
    signal s2

    function y() {
    }
    function z() {
    }
}

属性名を並べ替えずにグループ化するには、代わりに `--group-attributes-together ` を使用してください。

これにより、前のスニペットは次のようにフォーマットされます：

import QtQuick

QtObject {
    id: asdf

    property int h
    property int w
    property Item myItem2: Item {
        TextEdit {
        }
        Rectangle {
        }
    }
    property Item myItem: Item {
        Rectangle {
        }
        TextEdit {
        }
    }

    signal s2
    signal s1

    function z() {
    }
    function y() {
    }
}

このオプションは、--normalize よりも優先されます。

設定ファイル

qmlformat は、プロジェクトのソース内、またはプロジェクトのソースフォルダの親ディレクトリに設定ファイル（.qmlformat.ini ）を含めることで設定できます。--write-defaults フラグを指定すると、デフォルトの設定ファイルを取得できます。これにより、現在の作業ディレクトリに.qmlformat.ini ファイルが生成されます。

ファイルリストの書式設定

書式設定対象のファイル一覧を引数として渡すこともできますが、qmlformat には、ファイルに保存されている一連のファイルを処理するための-F オプションが用意されています。この場合、書式設定はインプレースで行われます。

// FileList.txt
main.qml
mycomponent.qml

このリストを使用するには：

qmlformat -F FileList.txt

セミコロンに関する規則

--semicolon-rule オプションを使用すると、JS 文の末尾にセミコロンを追加する方法をカスタマイズできます。

以下の値が指定可能です:

• always - 常にセミコロンを追加する（デフォルト）。
• essential - セミコロンを省略することで問題が生じない場合を除き、セミコロンを削除する。

コメントによる書式設定の無効化

特別なコメントを使用することで、qmlformatを一時的に無効にすることができます。

• // qmlformat off その行以降、書式設定を無効にします。
• // qmlformat on フォーマットを無効にした後、再び有効にします。

これにより、手作業で調整したコードや複雑な構造を、qmlformat によってレイアウトが変更されることなく維持することができます。書式設定は、次の// qmlformat on コメントが現れるまで、あるいは再有効化の指定が見つからない場合はファイルの終わりまで無効のままとなります。

書式設定ディレクティブを使用する際は、以下の点に留意してください:

• ディレクティブは必ず単独の行に記述する必要があります。
• ネストされたディレクティブはサポートされていません。最初の `// qmlformat off ` と、その直後の `// qmlformat on ` のみが考慮されます。無効化された領域内にある追加のディレクティブは無視されます。
• 正規化書式設定モードの場合、sortImports が有効になっている場合、または元の文書の順序を変更するオプションが使用されている場合、ディレクティブは無視されます。これらの場合、書式設定は常に適用されます。