신호 핸들러 매개변수

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 ` 신호를 가진 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.