信号处理程序参数

qmllint 将此警告类别标记为“[signal-handler-parameters] ”。

该警告类别包含多个警告，具体说明见以下各节：

未找到信号中的参数类型

发生了什么？

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

通常，当在 QML 中处理由 C++ 定义的信号时，如果包含该 C++ 定义信号的模块未正确向另一个 QML 模块声明其 QML 依赖关系，就会发生这种情况。如果包含该 C++ 定义信号的模块能够编译通过，则表明该依赖关系仅在 C++ 级别被声明，而未在QML 模块级别声明。

注意：如果您正在 导入具有外部依赖关系的 QML 模块，请确认这些模块已实际安装，且其模块位于导入路径中。

该警告也可能表明 C++ 定义信号的参数类型在 QML 中没有对应的类型。例如，该参数类型可能缺少 `QML_ELEMENT ` 宏。在此情况下，请参阅《从 C++ 定义 QML 类型》或《概述 - QML 与 C++ 集成》。

这有什么问题？

在第一种情况下，包含 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 头文件。此外，mymodule 对 Qt Quick。

现在，让我们尝试在 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。

受限类型语法

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