qmllint
qmllint es una herramienta incluida en Qt que verifica la validez sintáctica de los archivos QML. Puedes integrar qmllint en tu sistema de compilación para facilitar su uso. También advierte sobre algunos antipatrones de QML. Consulta «Configuración de las advertencias de qmllint» para saber cómo desactivar un tipo específico de advertencia.
Nota: Si utilizas un IDE, como Qt Creator, no es necesario que ejecutes qmllint manualmente. El IDE utiliza QML Language Server, que proporciona resultados de análisis y diagnósticos en tiempo real a medida que escribes.
Por defecto, algunos problemas darán lugar a advertencias que se mostrarán en pantalla. Si hay más advertencias de las que permite el límite configurable con --max-warnings, el código de salida será distinto de cero. Sin embargo, los problemas menores (como las importaciones no utilizadas) son, por defecto, meros mensajes informativos y nunca afectarán al código de salida. qmllint es muy configurable y permite desactivar las advertencias o modificar la forma en que se tratan.
qmllint advierte sobre:
- Accesos no calificados a propiedades
- Uso de controladores de señales sin una señal correspondiente
- El uso de sentencias «with» en QML
- Problemas relacionados con la compilación de código QML
- Importaciones no utilizadas
- Componentes y propiedades obsoletos
- Y muchas otras cosas
Consulta «Advertencias y errores de QML Lint » para saber cómo solucionar las advertencias y los errores de qmllint.
Nota: Para que qmllint funcione correctamente, necesita información sobre los tipos. Esa información la proporcionan los módulos QML en las rutas de importación. El directorio actual, así como las rutas de importación de los tipos integrados de Qt, se utilizan como rutas de importación por defecto. Para añadir más rutas de importación que no estén incluidas en las predeterminadas, añádelas mediante el indicador « -I ».
Para obtener una descripción general y una explicación de todas las opciones de línea de comandos disponibles, ejecuta qmllint --help.
Advertencias del compilador
qmllint puede avisarte de código que no puede compilarse con qmlsc.
Estas advertencias no están activadas por defecto. Para activarlas, configura qmllint para que utilice la categoría de advertencias del compilador.
Uso de qmllint con CMake
En los proyectos que utilizan la API de CMake qt_add_qml_module() para crear módulos QML, se crean automáticamente objetivos de conveniencia como all_qmllint. Estos ejecutan qmllint en todos los archivos QML de un módulo específico o del proyecto.
Aplicación automática de sugerencias de corrección
Resolver las advertencias emitidas por qmllint puede suponer bastante trabajo manual de edición y validación. Algunas de las advertencias que emite qmllint incluyen una sugerencia de corrección asociada que se puede activar para resolver la advertencia automáticamente. Para activar estas correcciones, puedes:
- Pasar «
--fix» a qmllint. - Activar las correcciones desde tu IDE.
Aplicar todas las correcciones del proyecto de una sola vez puede suponer un cambio demasiado grande. Por lo tanto, se recomienda dividir el trabajo en partes más manejables. Puedes dividir el trabajo analizando solo un subconjunto de los archivos o ejecutando únicamente determinadas categorías.
qmllint --only-explicit-categories --ignore-settings --fix --unqualified=warning <files>De este modo, se aplicarán las correcciones disponibles únicamente a los accesos no calificados, desactivando todas las demás categorías de advertencias con --only-explicit-categories y --ignore-settings.
Si no estás seguro de un cambio, utiliza --dry-run para ver de forma segura el resultado de una ejecución sin modificar realmente los archivos.
Marcar componentes y propiedades como obsoletos
qmllint te permite marcar tanto propiedades como componentes como obsoletos:
@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)
}Las advertencias de obsolescencia para los componentes se mostrarán cada vez que se cree el componente.
Desactivar las advertencias en línea
Puedes desactivar temporalmente las advertencias en un archivo en cualquier momento utilizando // qmllint disable.
Puedes hacerlo al final de una línea cuando una sola línea genere advertencias:
Item {
property string foo
Item {
property string bar: foo // qmllint disable unqualified
}
}Como alternativa, puedes desactivar las advertencias para un bloque de líneas colocando el comentario en una línea que solo contenga « // qmllint disable » y terminando el bloque con « // qmllint enable »:
Item {
property string foo
Item {
// qmllint disable unqualified
property string bar: foo
property string bar2: foo
// qmllint enable unqualified
}
}qmllint interpreta todos los comentarios de una sola línea que comienzan por qmllint como directivas. Por lo tanto, no debes comenzar un comentario de esa manera a menos que desees activar o desactivar advertencias.
Nota: Tal y como se ha hecho en los ejemplos anteriores, es preferible especificar explícitamente la advertencia o la lista de advertencias que se desean desactivar, en lugar de desactivarlas todas. Esto se puede hacer simplemente enumerando las categorías de advertencias después de « qmllint disable » (los nombres son los mismos que los de las opciones que aparecen en « --help »).
Configuración de las advertencias de qmllint
Puede configurar las advertencias que emite qmllint y su nivel de gravedad. Estos niveles pueden ser info, {warning}, error o disable. Puede personalizar las advertencias mediante el archivo de configuración .qmllint.ini o pasando opciones de línea de comandos a qmllint. Las opciones de línea de comandos tienen prioridad sobre los valores predeterminados y el archivo de configuración.
Para personalizar el nivel de una categoría de advertencia a través de la línea de comandos, establece la opción de línea de comandos correspondiente en el nivel deseado.
Por ejemplo, para desactivar las advertencias sobre elementos obsoletos, ejecuta qmllint con la opción --deprecated=disable. Y para convertir las importaciones no utilizadas en un error, pasa --unused-imports=error.
Se pueden personalizar las advertencias de forma más permanente modificando el archivo de configuración. Consulta la siguiente sección sobre los archivos « Settings » para obtener más detalles.
Configuración
Además de pasar opciones de línea de comandos, también puedes configurar qmllint mediante un archivo de configuración. La --write-defaults de línea de comandos te generará uno.
Los archivos de configuración se denominan « .qmllint.ini » y tienen este aspecto:
[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=warningLos niveles de advertencia se pueden establecer en « info », « warning », « error » o « disable », al igual que con las opciones de la línea de comandos.
qmllint buscará automáticamente un archivo de configuración en la ubicación del archivo QML que se está analizando. También revisa todos los directorios superiores para encontrar este archivo y aplica automáticamente la configuración que contiene. Puedes desactivar este comportamiento utilizando --ignore-settings. Siempre puedes anular estos valores predeterminados especificando parámetros de línea de comandos que tengan prioridad sobre los niveles de advertencia de la configuración.
Configuración de propiedades de contexto
Las propiedades de contexto se pueden definir o ignorar por su nombre en su propio archivo de configuración. La configuración de las propiedades de contexto permite un enfoque más detallado a la hora de desactivar las advertencias de acceso no calificado para los usos de propiedades de contexto, mientras que .qmllint.ini solo permite desactivar todas las advertencias de acceso no calificado, lo que podría incluir aquellas no relacionadas con las propiedades de contexto.
La configuración de las propiedades de contexto se denomina « .contextProperties.ini » y debe ubicarse dentro de la carpeta de código fuente de tu proyecto. Tiene el siguiente aspecto:
[General]
disableUnqualifiedAccess = "myContextProperty1,myContextProperty2"
warnOnUsage = "myContextProperty3,myContextProperty4,myContextProperty5"
disableHeuristic = falsePara desactivar las advertencias de qmllint sobre el acceso no calificado a un nombre de propiedad de contexto, añade el nombre de la propiedad de contexto a disableUnqualifiedAccess. Separa los nombres de varias propiedades de contexto con una coma.
Para que se muestren advertencias sobre el uso de propiedades de contexto, añade el nombre de la propiedad de contexto a warnOnUsage. Separa varios nombres de propiedades de contexto con una coma.
Para controlar la heurística de qmllint, configura disableHeuristic en true o false.
Scripting
qmllint puede escribir o generar JSON mediante la opción --json <file>, que devolverá JSON válido con mensajes de advertencia, la ubicación de las advertencias en el archivo y la línea, y su nivel de gravedad. Utiliza el nombre de archivo especial «-» para escribir en stdout en lugar de en un archivo. Esto puede utilizarse para integrar más fácilmente qmllint en tus hooks de pre-commit o en las pruebas de CI.
Nota: qmllint debe implementarse en un entorno aislado, un contenedor u otro entorno seguro cuando se ejecute con código no fiable.
Véase también «Archivos de descripción de tipos » y «Qt Quick: herramientas y utilidades».
© 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.