qmllint

qmllintは Qt に同梱されているツールで、QML ファイルの構文の妥当性を検証します。qmllint をビルドシステムに統合することで、利便性を高めることができます。また、一部の QML アンチパターンについても警告を出します。特定の警告タイプを無効にする方法については、「qmllint 警告の設定」を参照してください。

デフォルトでは、一部の問題に対して警告が出力されます。--max-warnings で設定可能な上限を超える警告が発生した場合、終了コードは0以外になります。 ただし、軽微な問題（未使用のインポートなど）は、デフォルトでは単なる情報メッセージとして扱われ、終了コードには一切影響しません。qmllintは高度にカスタマイズ可能であり、警告を無効にしたり、警告の処理方法を変更したりすることができます。

qmllint は以下の点について警告を出します：

• プロパティへの修飾子なしのアクセス
• 対応するシグナルがないシグナルハンドラの使用
• QML における with 文の使用
• QMLコードのコンパイルに関連する問題
• 未使用のインポート
• 非推奨のコンポーネントおよびプロパティ
• その他多数

qmllint の警告やエラーの修正方法については、「QML Lint の警告とエラー」を参照してください。

利用可能なすべてのコマンドラインオプションの概要と説明を確認するには、qmllint --help を実行してください。

コンパイラの警告

qmllint は、qmlsc でコンパイルできないコードについて警告を表示することができます。

これらの警告は、デフォルトでは有効になっていません。有効にするには、qmllint を設定して、コンパイラの警告カテゴリを使用するようにします。

CMake での qmllint の使用

QML モジュールを作成するためにqt_add_qml_module()CMake API を使用しているプロジェクトでは、all_qmllint などの便利なターゲットが自動的に作成されます。これらは、特定のモジュールまたはプロジェクトのすべての QML ファイルに対して qmllint を実行します。

修正提案の自動適用

qmllint によって出力された警告への対処には、かなりの手作業による編集や検証作業が必要になる場合があります。qmllint が出力する警告の中には、警告を自動的に解消するための修正提案が関連付けられているものがあります。これらの修正を実行するには、次の方法があります。

• qmllintに--fix 引数を渡します。
• IDEからfixitを有効にする。

プロジェクト全体で一度にすべてのフィックスを適用すると、変更の規模が大きくなりすぎる可能性があります。そのため、作業を管理しやすい部分に分けることをお勧めします。ファイルの一部のみをリンティング対象にしたり、特定のカテゴリのみを実行したりすることで、作業を分割できます。

qmllint --only-explicit-categories --ignore-settings --fix --unqualified=warning <files>

これにより、--only-explicit-categories および--ignore-settings を使用して他のすべての警告カテゴリを無効化し、修飾されていないアクセスに対して利用可能な修正項目のみを適用します。

変更内容に不安がある場合は、--dry-run を使用することで、実際にファイルを変更することなく、安全に実行結果を確認できます。

コンポーネントおよびプロパティを非推奨としてマークする

qmllint では、プロパティとコンポーネントの両方を非推奨としてマークすることができます:

@Deprecated { reason: "Use NewCustomText instead" }
Text {
    @Deprecated { reason: "Use newProperty instead" }
    property int oldProperty
    property int newProperty
    Component.onCompleted: console.log(oldProperty);  // Warning: XY.qml:8:40: Property "oldProperty" is deprecated (Reason: Use newProperty instead)
}

コンポーネントに対する非推奨警告は、そのコンポーネントが作成されるたびに表示されます。

インラインでの警告の無効化

// qmllint disable を使用することで、ファイル内の警告をいつでも一時的に無効にすることができます。

1行だけで警告が発生する場合は、その行の末尾で次のように指定します:

Item {
    property string foo
    Item {
        property string bar: foo // qmllint disable unqualified
    }
}

あるいは、// qmllint disable のみを含む行にコメントを記述し、そのブロックを// qmllint enable で終了させることで、行のブロック単位で警告を無効にすることもできます:

Item {
    property string foo
    Item {
        // qmllint disable unqualified
        property string bar: foo
        property string bar2: foo
        // qmllint enable unqualified
    }
}

qmllint は、qmllint で始まるすべての単一行コメントをディレクティブとして解釈します。したがって、警告を有効または無効にしたい場合を除き、その形式でコメントを開始しないでください。

qmllint の警告の設定

qmllint が出力する警告とその重大度レベルを設定できます。これらのレベルには、info 、{warning}、error 、またはdisable があります。警告の設定は、.qmllint.ini 設定ファイルを使用するか、qmllint にコマンドラインオプションを指定することでカスタマイズできます。コマンドラインオプションは、デフォルト設定および設定ファイルの設定よりも優先されます。

コマンドラインから警告カテゴリのレベルをカスタマイズするには、対応するコマンドラインオプションを希望のレベルに設定します。

たとえば、非推奨に関する警告を無効にするには、--deprecated=disable オプションを指定してqmllintを実行します。また、未使用のインポートをエラーとして扱うには、--unused-imports=error を指定します。

より永続的な方法で警告をカスタマイズするには、設定ファイルを編集します。詳細については、次の「Settings ファイル」のセクションを参照してください。

設定

コマンドラインオプションを指定するほか、設定ファイルを使用して qmllint を構成することもできます。コマンドラインで `--write-defaults ` と指定すると、設定ファイルが生成されます。

設定ファイルは.qmllint.ini という名前で、次のような形式になります：

[General]
DisableDefaultImports=false
MaxWarnings=-1

[Warnings]
AccessSingletonViaObject=warning
AliasCycle=warning
AssignmentInCondition=warning
AttachedPropertyReuse=disable
BadSignalHandlerParameters=warning
Comma=warning
CompilerWarnings=disable
ComponentChildrenCount=warning
ConfusingExpressionStatement=warning
ConfusingMinuses=warning
ConfusingPluses=warning
ContextProperties=warning
Deprecated=warning
DuplicateEnumEntries=warning
DuplicateImport=warning
DuplicateInlineComponent=warning
DuplicatePropertyBinding=warning
DuplicatedName=warning
EnumEntryMatchesEnum=warning
EnumsAreNotTypes=warning
EqualityTypeCoercion=warning
Eval=warning
FunctionUsedBeforeDeclaration=disable
ImportFailure=warning
IncompatibleType=warning
InheritanceCycle=warning
InvalidLintDirective=warning
LintPluginWarnings=disable
LiteralConstructor=warning
MissingEnumEntry=warning
MissingProperty=warning
MissingType=warning
MultilineStrings=info
NonListProperty=warning
NonRootEnum=warning
PreferNonVarProperties=warning
PrefixedImportType=warning
PropertyAliasCycles=warning
QtDesignStudio.FunctionsNotSupportedInQmlUi=warning
QtDesignStudio.ImperativeCodeNotEditableInVisualDesigner=warning
QtDesignStudio.InvalidIdeInVisualDesigner=warning
QtDesignStudio.ReferenceToParentItemNotSupportedByVisualDesigner=warning
QtDesignStudio.UnsupportedRootTypeInQmlUi=warning
QtDesignStudio.UnsupportedTypeInQmlUi=warning
Quick.Anchors=warning
Quick.AttachedPropertyReuse=disable
Quick.AttachedPropertyType=warning
Quick.Color=warning
Quick.ControlsAttachedPropertyReuse=disable
Quick.ControlsNativeCustomize=warning
Quick.LayoutsPositioning=warning
Quick.PropertyChangesParsed=warning
Quick.StateNoChildItem=warning
Quick.UnexpectedVarType=warning
ReadOnlyProperty=warning
RedundantOptionalChaining=warning
RequiredProperty=warning
RestrictedType=warning
StalePropertyRead=warning
TopLevelComponent=warning
TranslationFunctionMismatch=warning
UncreatableType=warning
UnintentionalEmptyBlock=warning
UnqualifiedAccess=warning
UnreachableCode=warning
UnresolvedAlias=warning
UnresolvedType=warning
UnterminatedCase=warning
UnusedImports=info
UseProperFunction=warning
VarUsedBeforeDeclaration=warning
Void=disable
WithStatement=warning

警告レベルは、コマンドラインオプションと同様に、info 、warning 、error 、またはdisable に設定できます。

qmllint は、リンティング対象の qml ファイルが置かれている場所に設定ファイルを自動的に検索します。また、このファイルを見つけるためにすべての親ディレクトリも検索し、そこに含まれる設定を自動的に適用します。--ignore-settings を使用することで、この動作を無効にできます。設定内の警告レベルよりも優先されるコマンドライン引数を指定することで、これらのデフォルト設定をいつでも上書きすることができます。

コンテキストプロパティの設定

コンテキストプロパティは、専用の設定ファイル内で名前を指定して定義または無視することができます。コンテキストプロパティの設定を使用すると、コンテキストプロパティの使用に関する未修飾アクセス警告を、よりきめ細かく無効にすることができます。一方、.qmllint.ini では、コンテキストプロパティに関連しないものも含む可能性のある、すべての未修飾アクセス警告を無効にすることしかできません。

コンテキストプロパティの設定は.contextProperties.ini という名前で、プロジェクトのソースフォルダ内に配置する必要があります。その形式は次のようになります：

[General]
disableUnqualifiedAccess = "myContextProperty1,myContextProperty2"
warnOnUsage = "myContextProperty3,myContextProperty4,myContextProperty5"
disableHeuristic = false

コンテキストプロパティ名への修飾なしのアクセスに関する qmllint の警告を無効にするには、disableUnqualifiedAccess にそのコンテキストプロパティ名を追加します。複数のコンテキストプロパティ名はコンマで区切ります。

コンテキストプロパティの使用について警告を表示するには、warnOnUsage にコンテキストプロパティ名を追加します。複数のコンテキストプロパティ名はコンマで区切ります。

qmllint のヒューリスティックを制御するには、disableHeuristic をtrue またはfalse に設定します。

スクリプト機能

qmllint は、--json <file> オプションを介して JSON を書き出したり出力したりできます。これにより、警告メッセージ、警告のファイルおよび行の位置、およびその重大度レベルを含む有効な JSON が返されます。ファイルではなく stdout に出力するには、特別なファイル名「-」を使用してください。これにより、qmllint をプレコミットフックや CI テストに簡単に統合できます。