Parámetros del controlador de señales
qmllint denomina a esta categoría de advertencias « [signal-handler-parameters] ».
Esta categoría de advertencias incluye varias advertencias, que se describen en las secciones siguientes:
No se ha encontrado el tipo de parámetro en la señal
¿Qué ha ocurrido?
Un controlador de señales ha intentado gestionar una señal con parámetros de tipos QML desconocidos.
Normalmente, esto ocurre al gestionar señales definidas en C++ en QML cuando el módulo con la señal definida en C++ no declara correctamente su dependencia de QML respecto a otro módulo QML. Si el módulo con la señal definida en C++ se compila, esto indica que la dependencia solo se declaró a nivel de C++ y no a nivel del módulo QML.
Nota: Si estás importando módulos QML con dependencias externas, comprueba que estén realmente instalados y que sus módulos se encuentren en una ruta de importación.
La advertencia también podría indicar que el tipo de parámetro de la señal definida en C++ no tiene un equivalente en QML. Por ejemplo, es posible que al tipo de parámetro le falte la macro ` QML_ELEMENT `. En este caso, consulta «Definición de tipos QML desde C++ » o «Descripción general: integración de QML y C++ ».
¿Por qué es un problema?
En el primer caso, el módulo con la señal de C++ tiene una dependencia no declarada a nivel del módulo QML, lo que dificulta el uso del módulo, ya que los usuarios deben adivinar las dependencias ocultas del mismo.
En ambos casos, las herramientas de QML no pueden encontrar el equivalente en QML del tipo de C++: ni el compilador puede compilar este controlador de señal a C++ ni qmllint QML Language Server analizar este controlador.
Ejemplo
Supongamos que nuestro módulo tiene una clase de C++ con una señal « helloWorld »:
#include <QQuickItem>
#include <QtQml/qqmlregistration.h>
#include <QObject>
class MyCppObject : public QObject
{
Q_OBJECT
QML_ELEMENT
public:
MyCppObject(QObject *parent = nullptr)
: QObject(parent)
{}
signals:
void helloWorld(QQuickItem *i);
};con el siguiente CMakeLists.txt:
find_package(Qt6 6.5 REQUIRED COMPONENTS Quick QuickControls2)
qt_standard_project_setup(REQUIRES 6.5)
qt_add_executable(mymodule
main.cpp
)
qt_add_qml_module(mymodule
URI MyModule
VERSION 1.0
QML_FILES Main.qml
SOURCES mycppobject.cpp mycppobject.h
)
# declare C++ dependency to Quick
target_link_libraries(appuntitled27
PRIVATE Qt6::Quick
)Se ha declarado la dependencia de C++ Quick, de modo que esta clase se pueda compilar y se pueda encontrar la inclusión QQuickItem. Además, mymodule no tiene ninguna dependencia de QML respecto a Qt Quick.
Ahora, intentemos gestionar esta señal « helloWorld » en QML:
import MyModule // name of the module with MyCppObject
MyCppObject {
onHelloWorld: function (x) { console.log(x); } // not ok: Type QQuickItem was not found!
}El motivo del mensaje de advertencia es que, en el código QML, « QQuickItem » y su equivalente en QML « Item » no se reconocen: ¡la dependencia QtQuick de MyModule no se había declarado en el archivo CMakeLists.txt!
Puedes añadirla de la siguiente manera en la llamada a `qt_add_qml_module()`:
qt_add_qml_module(mymodule
URI MyModule
...
# declare QML dependencies to QtQuick:
DEPENDENCIES QtQuick
...
)¡Ahora, el código QML debería volver a funcionar correctamente!
El controlador de señal tiene más parámetros formales que la señal que gestiona
¿Qué ha pasado?
Un controlador de señal espera más parámetros de los que la señal proporciona realmente.
¿Por qué es un problema?
Los parámetros adicionales quedarán sin definir.
Ejemplo
import QtQuick
Item {
signal helloWorld(x: QtObject) // signal expects only one parameter
onHelloWorld: function (x,y,z) {} // not ok: signal handler handles three parameters
}Para solucionar esta advertencia, elimina los parámetros adicionales del controlador de señal o añade los parámetros que faltan a la declaración de la señal:
import QtQuick
Item {
signal helloWorld(x: QtObject) // signal expects only one parameter
onHelloWorld: function (x) {} // ok: signal handler handles one parameter
signal alternativeHelloWorld(x: QtObject, y: int, y: int) // signal expects three parameters
onAlternativeHelloWorld: function (x,y,z) {} // ok: signal handler handles three parameters
}La señal tiene un parámetro con el mismo nombre
¿Qué ha pasado?
Es posible que la señal o el controlador de señales haya intercambiado algunos de sus argumentos, o que falten algunos de ellos.
¿Por qué es un problema?
Es muy probable que se trate de un error tipográfico y que no sea lo que el usuario pretendía.
Ejemplo
Argumentos que faltan
import QtQuick
Item {
signal helloWorld(x: QtObject, y: int)
onHelloWorld: function (y) {} // not ok: it seems that x was forgotten
}Para solucionar esta advertencia, añade los parámetros que faltan o cambia el nombre del primer parámetro:
import QtQuick
Item {
signal helloWorld(x: QtObject, y: int)
onHelloWorld: function (x, y) {} // ok: parameters have the same order as in helloWorld
signal alternativeHelloWorld(x: QtObject, y: int)
onAlternativeHelloWorld: function (x) {} // ok: parameters have the same order as in helloWorld, even if y is missing
}Argumentos intercambiados
import QtQuick
Item {
signal helloWorld(x: QtObject, y: int)
onHelloWorld: function (y, x) {} // not ok: helloWorld expects first 'x' then 'y'
}Para solucionar esta advertencia, reordena los parámetros en el orden correcto:
import QtQuick
Item {
signal helloWorld(x: QtObject, y: int)
onHelloWorld: function (x, y) {} // ok: parameters have the same order as in helloWorld
}Véase también qt_add_qml_module#declaring-module-dependencies.
© 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.