信号处理器参数

该警告类别由 qmllint 拼写[signal-handler-parameters] 。

该警告类别有多种警告，将在以下章节中说明：

未找到信号中的参数类型

发生了什么？

一个信号处理器试图处理一个带有未知 QML 类型参数的信号。

通常，在 QML 中处理 C++ 定义的信号时会发生这种情况，因为 C++ 定义信号的模块没有正确声明它与另一个 QML 模块的 QML 依赖关系。如果带有 C++ 定义信号的模块能编译，则表明只在 C++ 层而不是QML 模块层声明了依赖关系。

注意： 如果您导入的 QML 模块有外部依赖关系，请确认它们是否已安装，以及它们的模块是否在导入路径中。

警告还可能表明，C++ 定义信号的参数类型没有 QML 对应。例如，参数类型可能缺少QML_ELEMENT 宏。在这种情况下，请参阅Defining QML Types from C++或Overview - QML and C++ Integration。

为什么会这样？

在第一种情况下，带有 C++ 信号的模块在 QML 模块级别上有一个未声明的依赖关系，这就很难使用该模块，因为模块用户需要猜测模块的隐藏依赖关系。

在这两种情况下，QML 工具都无法找到 C++ 类型的 QML 对应：编译器无法将此信号处理器编译成 C++，qmllint以及 QML Language Server都无法分析这个处理程序。

示例

让我们的模块有一个带有helloWorld 信号的 C++ 类：

#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);

};

并带有以下 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
)

声明了 C++ 依赖关系Quick ，因此该类可以编译，并且可以找到QQuickItem include。此外，mymodule 并不依赖QtQuick 。

现在，让我们尝试用 QML 来处理这个helloWorld 信号：

import MyModule // name of the module with MyCppObject

MyCppObject {
    onHelloWorld: function (x) { console.log(x); } // not ok: Type QQuickItem was not found!
}

出现警告信息的原因是，在 QML 代码中，QQuickItem 及其 QML 对应的Item 并不知道：MyModule 的依赖关系 "QtQuick"没有在 CMakeLists.txt 中声明！

你可以在下面的 qt_add_qml_module() 调用中添加它：

qt_add_qml_module(mymodule
    URI MyModule
    ...
    # declare QML dependencies to QtQuick:
    DEPENDENCIES QtQuick
    ...
)

现在，QML 代码应该没问题了！

信号处理器的形式参数多于它所处理的信号

发生了什么事？

信号处理程序期望的参数多于信号实际提供的参数。

为什么会这样？

多余的参数将是未定义的。

示例

import QtQuick

Item {
    signal helloWorld(x: QtObject)  // signal expects only one parameter

    onHelloWorld: function (x,y,z) {} // not ok: signal handler handles three parameters
}

要修复此警告，请删除信号处理程序的额外参数，或在信号声明中添加缺失的参数：

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
}

信号有一个同名参数

发生了什么？

信号或信号处理程序可能交换了一些参数，或者丢失了一些参数。

为什么会这样？

这很可能是一个错字，并非用户有意为之。

示例

缺少参数

import QtQuick

Item {
    signal helloWorld(x: QtObject, y: int)

    onHelloWorld: function (y) {} // not ok: it seems that x was forgotten
}

要修复此警告，请添加丢失的参数或重命名第一个参数：

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
}

交换参数

import QtQuick

Item {
    signal helloWorld(x: QtObject, y: int)

    onHelloWorld: function (y, x) {} // not ok: helloWorld expects first 'x' then 'y'
}

要修复此警告，请按正确顺序重新排列参数：

import QtQuick

Item {
    signal helloWorld(x: QtObject, y: int)

    onHelloWorld: function (x, y) {} // ok: parameters have the same order as in helloWorld
}

另请参阅 qt_add_qml_module#declaring-module-dependencies。

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