QML 모듈
QML 모듈은 모듈을 임포트하는 클라이언트가 사용할 수 있는 타입 네임스페이스 내에서 버전 관리되는 타입과 JavaScript 리소스를 제공합니다. 모듈이 제공하는 타입은 플러그인 내의 C++에서 정의하거나 QML 문서에서 정의할 수 있습니다. 모듈은 QML 버전 관리 시스템을 활용하여 모듈을 독립적으로 업데이트할 수 있게 합니다.
QML 모듈을 정의하면 다음이 가능합니다:
- 프로젝트 내에서 공통 QML 유형 공유 — 예를 들어, 서로 다른 창에서 사용되는 UI 컴포넌트 그룹
- QML 기반 라이브러리의 배포
- 별개의 기능을 모듈화하여, 애플리케이션이 각자의 필요에 따라 필요한 라이브러리만 로드할 수 있도록 함
- 타입 및 리소스의 버전 관리를 통해 클라이언트 코드를 손상시키지 않고 모듈을 안전하게 업데이트할 수 있음
최신 QML 모듈
QML 모듈은 CMake API, 특히 qt_add_qml_module을 사용하여 정의하는 것이 가장 좋습니다. 다음 섹션에서는 최신 QML 모듈을 생성하는 데 필요한 모든 측면을 설명합니다.
QML 문서를 통한 객체 유형 정의
QML 유형은 QML 문서에서 직접 정의할 수 있으며, 이는 재사용 가능한 컴포넌트를 만드는 가장 간단한 방법입니다. 대문자로 시작하는 각 QML 파일은 동일한 모듈 내의 다른 QML 파일에서 사용할 수 있는 유형을 자동으로 정의합니다.
C++을 통한 QML 유형 정의
더 나은 성능을 얻거나 저수준 API에 접근하기 위해, C++에서 타입을 정의하고 이를 QML에 노출할 수 있습니다. C++ 타입은 정적 타입 지정 및 컴파일의 이점을 누리면서 속성, 메서드 및 시그널을 완벽하게 제어할 수 있게 해줍니다.
CMake를 통한 통합
qt_add_qml_module 라는 CMake 명령어는 QML 파일, C++ 타입 및 리소스를 하나의 통합된 모듈로 결합합니다. 이 명령어는 타입 등록, 리소스 컴파일 및 QML 툴 통합을 자동으로 처리하므로, 최신 QML 모듈 개발에 권장되는 방식입니다.
QML 모듈 현대화
이 가이드는 구형 CMake 기반 QML 모듈을 최신 버전의 Qt로 마이그레이션하는 데 도움을 줍니다. 여기서는 최신 CMake 정책에 적응하고 구식 기법을 피하는 방법을 다룹니다.
QML 모듈 미세 조정
『 QML 모듈 작성 』에 소개된 고급 모듈 구성 옵션을 사용하면 모듈 동작을 세밀하게 제어할 수 있습니다. 여기에는 동일한 바이너리에 여러 QML 모듈 추가, 버전 관리, 사용자 지정 디렉터리 레이아웃, QML 플러그인에 대한 심화 주제가 포함됩니다.
구형 QML 모듈
참고: QML 모듈을 정의할 때는 CMake API 를사용하십시오 . ` qmake`를 사용해야 하는 경우에만 QML 모듈을 수동으로 정의하십시오.
모듈은 모듈 정의 qmldir 파일로 정의됩니다. 각 모듈에는 모듈의 식별자인 관련 유형 네임스페이스가 있습니다. 모듈은 QML 객체 유형(QML 문서로 정의되거나 C++ 플러그인을 통해 정의됨)과 JavaScript 리소스를 제공할 수 있으며, 클라이언트에서 가져올 수 있습니다.
모듈을 정의하려면 개발자는 해당 모듈에 속하는 다양한 QML 문서, 자바스크립트 리소스 및 C++ 플러그인을 하나의 디렉터리에 모아두고, 적절한 모듈 정의 qmldir 파일을 작성하여 이 디렉터리에 함께 배치해야 합니다. 그런 다음 해당 디렉터리를 모듈로 QML 임포트 경로에 설치할 수 있습니다.
모듈을 정의하는 것이 프로젝트 내에서 공통 QML 유형을 공유하는 유일한 방법은 아니라는 점에 유의하십시오. 이 목적을 위해 간단한 QML 문서 디렉터리 임포트도 사용할 수 있습니다.
지원되는 QML 모듈 유형
QML에서 지원하는 모듈에는 두 가지 유형이 있습니다:
식별된 모듈은 식별자를 명시적으로 정의하며 QML 임포트 경로에 설치됩니다. 식별된 모듈은 (타입 버전 관리 덕분에) 유지 관리가 더 용이하며, 레거시 모듈에는 제공되지 않는 타입 등록 보장을 QML 엔진으로부터 받습니다. 레거시 모듈은 레거시 코드가 최신 버전의 QML에서도 계속 작동할 수 있도록 지원하기 위한 목적으로만 제공되며, 클라이언트는 가능한 한 사용을 피해야 합니다.
클라이언트는 QML 문서나 JavaScript 파일 내에서 QML 모듈을 임포트할 수 있습니다. 이 주제에 대한 자세한 내용은 QML 모듈 임포트에 관한 문서를 참조하십시오.
C++ 플러그인에서 유형 및 기능 제공
C++로 구현된 로직이 많거나, C++에서 타입을 정의하여 QML에 노출하는 애플리케이션의 경우 QML 플러그인을 구현하고자 할 수 있습니다. QML 확장 모듈 개발자는 더 나은 성능이나 더 큰 유연성을 얻기 위해(QML 문서를 통해 정의하는 대신) C++ 플러그인에서 일부 타입을 구현하고자 할 수 있습니다.
QML용 모든 C++ 플러그인에는 QML 엔진이 플러그인을 로드할 때 호출되는 초기화 함수가 있습니다. 이 초기화 함수는 플러그인이 제공하는 모든 타입을 등록해야 하지만, 그 외의 작업(예: QObject 인스턴스화)은 수행해서는 안 됩니다.
자세한 내용은 ‘QML용 C++ 플러그인 만들기’를 참조하십시오.
'QML 모듈 현대화 ' 및 'QML 모듈을 CMake로 이식하기'도 참조하십시오 .
© 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.
