qmllint

qmllint es una herramienta incluida con 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 anti-patrones QML. Consulte {Configuración de las advertencias de qmllint} para saber cómo desactivar un tipo de advertencia específico.

Por defecto, algunas cuestiones darán lugar a advertencias que se imprimirán. Si hay más advertencias que un límite que puede configurarse con --max-warnings, el código de salida será distinto de cero. Sin embargo, los problemas menores (como las importaciones no utilizadas) son sólo mensajes informativos por defecto y nunca afectarán al código de salida. qmllint es muy configurable y permite desactivar las advertencias o cambiar la forma en que se tratan.

qmllint advierte sobre:

• Accesos no cualificados a propiedades
• Uso de manejadores de señal sin una señal correspondiente
• 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

Consulte Advertencias y errores de QML Lint para saber cómo corregir las advertencias y errores de qmllint.

Para obtener una visión general y una explicación de todas las opciones disponibles en la línea de comandos, ejecute qmllint --help.

Advertencias del compilador

qmllint puede advertirle sobre código que no puede ser compilado por qmlsc.

Estas advertencias no están activadas por defecto. Para habilitarlas, configure qmllint para utilizar la categoría de advertencias del compilador.

Uso de qmllint con CMake

Para los proyectos que utilizan el qt_add_qml_module() CMake API para la creación de módulos QML, objetivos de conveniencia como all_qmllint se crean automáticamente. Estos ejecutan qmllint en todos los archivos QML de un módulo específico o del proyecto.

Marcar componentes y propiedades como obsoletos

qmllint 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)
}

Los avisos de obsoletos para los componentes se mostrarán cada vez que se cree el componente.

Deshabilitar advertencias en línea

En cualquier momento puede desactivar temporalmente las advertencias en un archivo utilizando // qmllint disable.

Puede hacerlo al final de una línea cuando una sola línea produzca advertencias:

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

Alternativamente, puede desactivar los comentarios para un bloque de líneas poniendo el comentario en una línea que sólo contenga // qmllint disable, 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 con qmllint como directivas. Por lo tanto, no debe comenzar un comentario de esa manera a menos que desee activar o desactivar advertencias.

Configuración de las advertencias de qmllint

Puede configurar las advertencias que emite qmllint y su nivel de gravedad. Estos niveles pueden ser info, {advertencia}, error, o disable. Puede personalizar las advertencias utilizando el archivo de configuración .qmllint.ini o pasando opciones de línea de comandos a qmllint. Las opciones de línea de comandos anulan el valor predeterminado 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, establezca la opción de línea de comandos correspondiente en el nivel deseado.

Por ejemplo, para desactivar las advertencias sobre depreciaciones, llame a qmllint con la opción --deprecated=disable. Y para convertir las importaciones no utilizadas en un error, pase --unused-imports=error.

Se pueden personalizar las advertencias de forma más permanente modificando el archivo de configuración. Para más información, consulte la sección sobre archivos de configuración.

Configuración

Además de pasar opciones de línea de comandos, también puede configurar qmllint mediante un archivo de configuración. La línea de comandos --write-defaults generará uno para usted.

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=warning

Los niveles de advertencia pueden establecerse 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á creando. También busca en todos los directorios padre para encontrar este archivo y aplica automáticamente la configuración que contiene. Puede desactivar este comportamiento utilizando --ignore-settings. Siempre puede anular estos valores predeterminados especificando parámetros de línea de comandos que tienen prioridad sobre los niveles de advertencia en la configuración.

Configuración de las propiedades de contexto

Las propiedades de contexto pueden definirse o ignorarse por nombre en su propio archivo de configuración. Los ajustes de propiedades de contexto permiten un enfoque más preciso para desactivar las advertencias de acceso no cualificado para usos de propiedades de contexto, mientras que .qmllint.ini sólo permite desactivar todas las advertencias de acceso no cualificado, incluyendo potencialmente las no relacionadas con propiedades de contexto.

Los ajustes de las propiedades de contexto se denominan .contextProperties.ini y deben encontrarse dentro de la carpeta de código fuente del proyecto. Su aspecto es el siguiente

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

Para desactivar las advertencias de qmllint sobre el acceso no cualificado a un nombre de propiedad de contexto, añada el nombre de la propiedad de contexto a disableUnqualifiedAccess. Separe varios nombres de propiedades de contexto con una coma.

Para advertir sobre el uso de propiedades de contexto, añada el nombre de la propiedad de contexto a warnOnUsage. Separe varios nombres de propiedades de contexto con una coma.

Para controlar la heurística qmllint, establezca disableHeuristic en true o false.

Escritura

qmllint puede escribir o dar salida a JSON mediante la opción --json <file> que devolverá JSON válido con mensajes de advertencia, ubicación de archivo y línea de las advertencias y su nivel de gravedad. Utilice el nombre de archivo especial '-' para escribir en stdout en lugar de en un archivo. Esto se puede utilizar para integrar más fácilmente qmllint en sus ganchos pre-commit o pruebas CI.