Análisis estático de QML 1: configuración básica

En este capítulo se presenta la estructura básica de un complemento de extensión de qmllint y cómo se puede utilizar con qmllint.

Para crear nuestro complemento, primero debemos habilitar el módulo QmlCompiler:

find_package(Qt6 REQUIRED COMPONENTS QmlCompiler)

A continuación, creamos un complemento y lo vinculamos al módulo QmlCompiler.

qt_add_plugin(HelloWorldPlugin)

target_sources(HelloWorldPlugin
    PRIVATE
        helloplugin.h
        helloplugin.cpp
)

target_link_libraries(HelloWorldPlugin PRIVATE Qt::QmlCompiler)

La implementación sigue el patrón para ampliar Qt con un complemento: creamos una subclase de ` QQmlSA::LintPlugin`,

class HelloWorldPlugin : public QObject, public QQmlSA::LintPlugin
{
    Q_OBJECT
    Q_PLUGIN_METADATA(IID QmlLintPluginInterface_iid FILE "plugin.json")
    Q_INTERFACES(QQmlSA::LintPlugin)

public:
    void registerPasses(QQmlSA::PassManager *manager, const QQmlSA::Element &rootElement) override;
};

El complemento hace referencia a un archivo ` plugin.json `, que contiene información importante:

{
    "name": "HelloWorld",
    "author": "Qt Example",
    "description": "Demonstrates how to write a qmllint plugin",
    "version": "1.0",
    "loggingCategories": [
        {
            "name": "hello-world",
            "settingsName": "HelloWorld",
            "description": "Used to create test messages"
        }
    ]
}

name, author, version y description son metadatos que describen el complemento.

Cada complemento puede tener una o más categorías de registro, que se utilizan para agrupar las advertencias por temas. loggingCategories admite una matriz de categorías, cada una de las cuales consta de

  • name, que sirve para identificar la categoría, y como nombre de la bandera en qmllint,
  • settingsName, que se utiliza para configurar la categoría en qmllint.ini
  • description, que debe describir qué tipo de mensajes de advertencia se etiquetan con la categoría

En nuestro ejemplo, solo tenemos una categoría de registro, hello-world. Para cada categoría, debemos crear un objeto LoggerWarningId en nuestro complemento.

static constexpr QQmlSA::LoggerWarningId helloWorld { "Plugin.HelloWorld.hello-world" };

Lo creamos con un literal de cadena que debe tener el formato « Plugin.<plugin name>.<category name> ».

Por último, para que nuestro complemento haga realmente algo útil, tenemos que implementar la función ` registerPasses `.

void HelloWorldPlugin::registerPasses(QQmlSA::PassManager *manager, const QQmlSA::Element &rootElement)
{
    const bool pluginIsEnabled = manager->isCategoryEnabled(helloWorld);
    qDebug() << "Hello World plugin is" << (pluginIsEnabled ? "enabled" : "disabled");
   if (!pluginIsEnabled)
        return; // omitir el registro si el complemento está desactivado de todos modos
    // aquí registraremos más adelante nuestros pases
}

Comprobamos si nuestra categoría está habilitada y mostramos un mensaje de diagnóstico que indica su estado mediante qDebug. Ten en cuenta que, por el momento, el complemento no realiza ninguna acción útil, ya que no hemos registrado ningún pase. Esto lo haremos en la siguiente parte de este tutorial.

Sin embargo, ya podemos comprobar que nuestro complemento se detecta correctamente. Utilizamos el siguiente comando para comprobarlo:

qmllint -P /path/to/the/directory/containing/the/plugin --Plugin.HelloWorld.hello-world info test.qml

La opción « -P » indica a qmllint que busque complementos en la carpeta especificada. Para evitar conflictos con las categorías internas de Qt, las categorías de los complementos siempre llevan el prefijo «Plugin», seguido de un punto, el nombre del complemento, otro punto y, por último, la categoría. Al ejecutar el comando debería aparecer el mensaje « Hello World Plugin is enabled ».

© 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.