Análisis estático de QML 2: pasada personalizada

En este capítulo se muestra cómo se pueden añadir pasadas de análisis personalizadas a qmllint, ampliando el complemento que hemos creado en el capítulo anterior. A modo de demostración, crearemos un complemento que compruebe si los elementos ` Text ` tienen asignado «Hello world!» en su propiedad `text`.

Para ello, creamos una nueva clase derivada de ` ElementPass`.

Nota: Hay dos tipos de pases que los complementos pueden registrar: ` ElementPasses` y ` PropertyPasses`. En este tutorial, solo tendremos en cuenta el más sencillo: ` ElementPass`.

class HelloWorldElementPass : public QQmlSA::ElementPass
{
public:
    HelloWorldElementPass(QQmlSA::PassManager *manager);
    bool shouldRun(const QQmlSA::Element &element) override;
    void run(const QQmlSA::Element &element) override;
private:
    QQmlSA::Element m_textType;
};

Dado que nuestro ` HelloWorldElementPass ` debe analizar elementos ` Text `, necesitamos una referencia al tipo ` Text `. Podemos utilizar la función ` resolveType ` para obtenerla. Como no queremos volver a resolver el tipo constantemente, lo hacemos una sola vez en el constructor y almacenamos el tipo en una variable miembro.

HelloWorldElementPass::HelloWorldElementPass(QQmlSA::PassManager *manager)
    : QQmlSA::ElementPass(manager)
{
    m_textType = resolveType("QtQuick", "Text");
}

La lógica real de nuestra pasada se lleva a cabo en dos funciones: shouldRun y run. Se ejecutarán en todos los elementos del archivo que qmllint analice.

En nuestro método shouldRun, comprobamos si el elemento actual deriva de Text y si tiene un enlace en la propiedad text.

bool HelloWorldElementPass::shouldRun(const QQmlSA::Element &element)
{
    if (!element.inherits(m_textType))
        return false;
    if (!element.hasOwnPropertyBindings(u"text"_s))
        return false;
    return true;
}

Solo los elementos que superen estas comprobaciones serán analizados posteriormente por nuestro «pass» a través de su método ` run `. Sería posible realizar todas las comprobaciones dentro de la propia función ` run `, pero, por lo general, es preferible separar las responsabilidades, tanto por cuestiones de rendimiento como para mejorar la legibilidad del código.

En nuestra función ` run `, recuperamos los enlaces a la propiedad `text`. Si el valor vinculado es un literal de cadena, comprobamos si se trata del saludo que esperamos.

void HelloWorldElementPass::run(const QQmlSA::Element &element)
{
    auto textBindings = element.ownPropertyBindings(u"text"_s);
    for (const auto &textBinding: textBindings) {
        if (textBinding.bindingType() != QQmlSA::BindingType::StringLiteral)
            continue;
        if (textBinding.stringValue() != u"Hello world!"_s)
            emitWarning("Incorrect greeting", helloWorld, textBinding.sourceLocation());
    }
}

Nota: La mayoría de las veces, a una propiedad solo se le asignará un enlace. Sin embargo, podría darse el caso, por ejemplo, de que a una misma propiedad se le asignaran un enlace literal y un ` Behavior `.

Por último, debemos crear una instancia de nuestro «pass» y registrarla con el ` PassManager`. Para ello, añadimos

    manager->registerElementPass(std::make_unique<HelloWorldElementPass>(manager));

a las funciones de « registerPasses » de nuestro complemento.

Podemos probar nuestro complemento ejecutando qmllint en un archivo de ejemplo mediante

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

Si « test.qml » tiene el siguiente aspecto

import QtQuick

Item {
     id: root

     property string greeting: "Hello"

     component MyText : Text {}

     component NotText : Item {
         property string text
     }

     Text { text: "Hello world!" }
     Text { text: root.greeting }
     Text { text: "Goodbye world!" }
     NotText {
         text: "Does not trigger"
          MyText { text: "Goodbye world!" }
     }
}

obtendremos

Info: test.qml:22:26: Incorrect greeting [Plugin.HelloWorld.hello-world]
          MyText { text: "Goodbye world!" }
                         ^^^^^^^^^^^^^^^^
Info: test.qml:19:19: Incorrect greeting [Plugin.HelloWorld.hello-world]
     Text { text: "Goodbye world!" }

como resultado. Podemos hacer algunas observaciones al respecto:

  • El primer « Text » contiene el saludo esperado, por lo que no hay ninguna advertencia
  • El segundo Text mostraría en tiempo de ejecución una advertencia errónea ("Hello" en lugar de "Hello world". Sin embargo, qmllint no puede detectar esto (en general), ya que no hay un enlace literal, sino un enlace a otra propiedad. Como solo comprobamos los enlaces literales, simplemente omitimos este enlace.
  • En cuanto a la vinculación literal del tercer elemento Text, advertimos correctamente del saludo incorrecto.
  • Dado que ` NotText ` no deriva de ` Text`, el análisis lo omitirá, ya que la comprobación de ` inherits ` lo descartará.
  • El elemento personalizado MyText hereda de Text y, en consecuencia, vemos la advertencia esperada.

En resumen, hemos visto los pasos necesarios para ampliar qmllint con pasadas personalizadas, y también hemos tomado conciencia de las limitaciones de las comprobaciones estáticas.

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