qmllint
qmllint是一个随 Qt Qml 提供的工具，可验证 QML 文件的语法有效性。您可以将 qmllint 集成到您的构建系统中，以方便使用。它还会对一些 QML 反模式提出警告。有关如何禁用特定警告类型，请参阅 {配置 qmllint 警告}。
注意： 使用Qt Creator 等集成开发环境时，无需手动运行qmllint 。集成开发环境使用 QML Language Server，它可在您键入时提供实时蚀刻输出和诊断。
默认情况下，某些问题会导致打印出警告。如果警告数量超过限制（可通过--max-warnings 进行配置），退出代码将不会为零。qmllint 具有很强的可配置性，允许禁用警告或更改处理方式。
qmllint 会发出以下警告
- 对属性的非限定访问
- 使用没有匹配信号的信号处理器
- 在 QML 中使用 with 语句
- 与编译 QML 代码有关的问题
- 未使用的导入
- 过时的组件和属性
- 以及许多其他问题
请参阅QML Lint Warning and Errors了解如何修复 qmllint 警告和错误。
注意： 为了让 qmllint 正常工作，它需要类型信息。这些信息由 QML 模块在导入路径中提供。默认情况下，当前目录以及 Qt 内置类型的导入路径被用作导入路径。要添加更多未包含在默认值中的导入路径，可通过-I 标志添加。
要获得所有可用命令行选项的概述和解释，请运行qmllint --help 。
编译器警告
qmllint 可以就qmlsc 无法编译的代码发出警告。
这些警告默认情况下不启用。要启用这些警告，请将qmllint 配置为使用编译器警告类别。
在 CMake 中使用 qmllint
对于使用qt_add_qml_module()CMake API 创建 QML 模块的项目，会自动创建all_qmllint 等便利目标。这些目标会在特定模块或项目的所有 QML 文件上运行 qmllint。
将组件和属性标记为过时
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 在文件中临时禁用警告。
当一行产生警告时，可以在行尾禁用警告：
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 disable 后列出警告类别（名称与--help 中列出的选项相同）。
配置 qmllint 警告
你可以配置 qmllint 发出的警告及其严重程度。这些级别可以是info 、{警告}、error 或disable 。你可以使用.qmllint.ini 设置文件或通过向 qmllint 传递命令行选项来定制警告。命令行选项会覆盖默认值和设置文件。
要通过命令行自定义警告类别的级别，可将相应的命令行选项设置为所需级别。
例如，若要禁用有关废弃的警告，可使用--deprecated=disable 选项调用 qmllint。要将未使用的导入变成错误，可通过--unused-imports=error 。
修改设置文件可以更持久地自定义警告。更多详情，请参阅接下来的 "设置文件 "章节。
设置文件
除了传递命令行选项，还可以通过设置文件配置 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 测试中。
另请参阅 类型描述文件和Qt Quick 工具和实用程序。
© 2026 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.
