シグナルハンドラのパラメータ

この警告カテゴリは、qmllint によって「[signal-handler-parameters] 」と表記されます。

この警告カテゴリには複数の警告があり、以下のセクションで説明されています：

シグナル内のパラメータの型が見つかりませんでした

何が起きたのか？

シグナルハンドラが、QML 型として認識できないパラメータを持つシグナルを処理しようとした。

通常、これは QML 内で C++ で定義されたシグナルを処理する際に、そのシグナルを含むモジュールが、別の QML モジュールへの QML 依存関係を適切に宣言していない場合に発生します。C++ で定義されたシグナルを含むモジュールがコンパイルされる場合、これは依存関係がQML モジュールレベルではなく、C++ レベルでのみ宣言されていたことを示しています。

注：外部依存関係を持つ QML モジュールをインポートしている場合は 、それらが実際にインストールされていること、およびそれらのモジュールがインポートパスに含まれていることを確認してください。

また、この警告は、C++で定義されたシグナルのパラメータ型にQML側の対応する型がないことを示している可能性もあります。例えば、パラメータ型にQML_ELEMENT マクロが指定されていない場合などです。この場合は、「C++からのQML型の定義」または「概要 - QMLとC++の統合」を参照してください。

なぜこれが問題なのでしょうか？

最初のケースでは、C++シグナルを持つモジュールがQMLモジュールレベルで宣言されていない依存関係を持っているため、モジュールの利用が困難になります。モジュールの利用者は、そのモジュールの隠れた依存関係を推測しなければならないからです。

どちらの場合も、QMLツールはC++型のQML側の対応物を見つけることができません。コンパイラはこのシグナルハンドラをC++にコンパイルできず、qmllintも QML Language Server このハンドラを解析することもできません。

例

このモジュールに、helloWorld シグナルを1つ持つ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.