플러그인과 함께 QML 모듈 사용하기

QML 모듈은 C++ 플러그인을 사용하여 C++로 정의된 컴포넌트를 Qt Quick 애플리케이션에 노출할 수 있습니다.

QML 모듈을 생성하려면:

1. 사용자 정의 컴포넌트를 생성하고 모든 .qml 파일을 해당 모듈 전용 디렉터리에 배치합니다. 예를 들어, imports\asset_imports.
2. Qt Quick UI 프로토타입 프로젝트(.qmlproject)의 경우, 모듈을 사용하려는 애플리케이션의 ` .qmlproject ` 파일에서 ` importPaths ` 변수의 값으로 모듈이 포함된 디렉터리의 경로를 지정합니다. 예: importPaths: [ "imports", "asset_imports" ].
3. 모듈에 대한 ` qmldir ` 파일을 생성하여 모듈 디렉터리에 배치하십시오. 자세한 내용은 ‘모듈 정의 qmldir 파일’을 참조하십시오.
4. 모듈 디렉터리에 designer 라는 이름의 디렉터리를 생성하십시오.
5. 모듈에 대한 .metainfo 파일을 생성하여 designer 디렉터리에 배치하십시오. qtquickcontrols2.metainfo 와 같이 Qt XML과 함께 제공되는 메타정보 파일을 예시로 사용하십시오.
6. 'QML 모듈 가져오기'에 설명된 대로 모듈을 프로젝트로 가져오십시오.

Qt 6.1 이하 버전으로 개발하는 경우

Qt 6.2부터는 CMake가 qmltypes 및 qmldir 파일을 자동으로 생성합니다.

유형 설명 파일 생성

QML 타입을 등록할 때는 QML 모듈에 plugins.qmltypes 파일이 있는지 확인하십시오. 이상적으로는 이 파일이 qmldir 파일과 동일한 디렉터리에 위치해야 합니다. qmltypes 파일에는 모듈의 플러그인이 내보내는 컴포넌트에 대한 설명이 포함되어 있으며, 모듈이 임포트될 때 Qt Creator 에 의해 로드됩니다.

자세한 내용은 ‘유형 설명 파일’을 참조하십시오.

플러그인 자동 덤프

플러그인이 포함된 모듈에 qmltypes 파일이 없는 경우, Qt Creator 는 백그라운드에서 qmldump 프로그램을 실행하여 임시 파일을 직접 생성하려고 시도합니다. 그러나 이 자동 덤프 기능은 오류 발생 가능성이 많은 대체 메커니즘이므로, 이를 전적으로 신뢰해서는 안 됩니다.

QML 모듈 가져오기

기본적으로 Qt Creator 는 Qt의 Qml 임포트 경로에서 Qml 모듈을 검색합니다.

qmake를 사용하고 있으며, 애플리케이션에서 Qt Creator 가 사용해야 할 추가 임포트 경로를 추가한 경우, 애플리케이션의 .pro 파일에서 QML_IMPORT_PATH 를 사용하여 해당 경로를 지정하십시오: QML_IMPORT_PATH += path/to/module.

CMake를 사용하는 경우, CMakeLists.txt 파일에 다음 명령을 추가하여 QML 임포트 경로를 설정하십시오:

set(QML_IMPORT_PATH ${CMAKE_SOURCE_DIR}/qml ${CMAKE_BINARY_DIR}/imports CACHE STRING "" FORCE)

이 임포트 경로는 CMake 프로젝트에서 빌드되는 모든 타깃에 영향을 미칩니다.

디자인 모드에서 QML 모듈 실행

QML Puppet은 Design 모드에서 이미지를 렌더링 및 미리 보고 데이터를 수집하는 데 사용됩니다. QML 모듈의 사용자 정의 컴포넌트를 올바르게 렌더링하려면, QML Puppet을 QML 모듈과 동일한 Qt 버전 및 컴파일러로 빌드해야 합니다.

플러그인은 QML Puppet에 의해 실행되는지, 아니면 애플리케이션에 의해 실행되는지에 따라 다르게 동작해야 합니다. 예를 들어, 애니메이션은 Design 모드에서는 실행되어서는 안 됩니다. QML_PUPPET_MODE 환경 변수의 값을 사용하여 플러그인이 현재 애플리케이션에 의해 실행되고 있는지, 아니면 Design 모드에서 편집되고 있는지 확인할 수 있습니다.