식별된 모듈

식별된 모듈이란 설치되어 있으며, QML 엔진에서 점으로 구분된 식별자 문자열 형태의 URI를 통해 식별할 수 있는 모듈을 말합니다. 이 URI는 해당 모듈의 ` qmldir ` 파일에 명시되어야 합니다. 이를 통해 해당 모듈은 로컬 파일 시스템 내 어디에 위치하든 변하지 않는 고유한 식별자로 가져올 수 있습니다.

식별된 모듈을 임포트할 때는 따옴표로 묶이지 않은 식별자와 선택적인 버전 번호가 사용됩니다:

import QtQuick
import com.mycompany.qml.mymodule 1.0

식별된 모듈은 QML 엔진이 이를 찾을 수 있도록 임포트 경로에 설치되어야 합니다.

구문상, URI의 점(.)으로 구분된 각 세그먼트는 올바른 형식의 ECMAScript 식별자 이름이어야 합니다. 즉, 예를 들어 세그먼트는 숫자로 시작해서는 안 되며, - (마이너스) 문자를 포함해서는 안 됩니다. URI는 디렉터리 이름으로 변환되므로, 라틴 알파벳의 영숫자, 밑줄 및 점으로만 구성해야 합니다.

로컬에 설치된 식별된 모듈

QML 및/또는 C++ 파일이 포함된 디렉터리는 모듈 메타데이터가 포함된 qmldir 파일을 갖추고 QML 임포트 경로에 설치되어 있다면 식별된 모듈로 공유될 수 있습니다. 로컬 파일 시스템에 있는 모든 QML 파일은 모듈의 URI를 참조하는 import 문을 사용하여 이 디렉터리를 모듈로 가져올 수 있으며, 이를 통해 파일은 모듈에 정의된 QML 객체 유형과 JavaScript 리소스를 사용할 수 있습니다.

모듈의 ` qmldir ` 파일은 URI의 점(.)으로 구분된 식별자 문자열을 반영하는 import 경로 내의 디렉터리 구조에 위치해야 하며, 식별자 내의 각 점(".")은 디렉터리 트리의 하위 레벨을 나타냅니다. 예를 들어, 모듈 ` com.mycompany.mymodule `의 ` qmldir ` 파일은 import 경로 내의 어딘가에 있는 ` com/mycompany/mymodule/qmldir ` 하위 경로에 위치해야 합니다.

모듈의 서로 다른 버전을 해당 모듈의 하위 디렉터리에 저장할 수 있습니다. 예를 들어, 모듈의 버전 2.1은 com/mycompany/mymodule.2/qmldir 또는 com/mycompany/mymodule.2.1/qmldir 아래에 위치할 수 있습니다. 엔진은 가장 잘 일치하는 모듈을 자동으로 로드합니다.

또는 qmldir 파일 내에서 서로 다른 유형에 대한 버전 관리를 정의할 수도 있지만, 이 경우 해당 모듈을 업데이트하기가 더 어려워질 수 있습니다(업데이트 절차의 일환으로 qmldir 파일 병합이 이루어져야 하기 때문입니다).

예시

다음과 같은 QML 프로젝트 디렉터리 구조를 고려해 보겠습니다. 최상위 디렉터리 myapp 아래에는 mycomponents 라는 하위 디렉터리에 공통 UI 컴포넌트 세트가 있고, main 라는 하위 디렉터리에 메인 애플리케이션 코드가 다음과 같이 위치해 있습니다:

myapp
    |- mycomponents
        |- CheckBox.qml
        |- DialogBox.qml
        |- Slider.qml
    |- main
        |- application.qml

mycomponents 디렉터리를 식별된 모듈로 사용할 수 있게 하려면, 해당 디렉터리에 모듈 식별자를 정의하고 모듈에서 제공하는 객체 유형을 설명하는 qmldir 파일이 포함되어야 합니다. 예를 들어, CheckBox, DialogBox 및 Slider 유형을 모듈 버전 1.0에서 사용할 수 있게 하려면, qmldir 파일에 다음 내용이 포함되어야 합니다:

module myapp.mycomponents
CheckBox 1.0 CheckBox.qml
DialogBox 1.0 DialogBox.qml
Slider 1.0 Slider.qml

또한, import 경로 내의 qmldir 파일 위치는 모듈의 점 구분 식별자 문자열과 일치해야 합니다. 예를 들어, 최상위 myapp 디렉터리가 C:\qml\projects 에 위치해 있고, 모듈이 "myapp.mycomponents"로 식별되어야 한다고 가정해 봅시다. 이 경우:

• C:\qml\projects 경로를 임포트 경로에 추가해야 합니다.
• qmldir 파일은 다음 위치에 있어야 합니다. C:\qml\projects\myapp\mycomponents\qmldir

이 작업이 완료되면, 로컬 파일 시스템의 어느 위치에 있든 QML 파일은 해당 모듈의 URI와 적절한 버전을 참조하여 모듈을 임포트할 수 있습니다:

import myapp.mycomponents 1.0

DialogBox {
    CheckBox {
        // ...
    }
    Slider {
        // ...
    }
}

원격으로 설치된 식별된 모듈

식별된 모듈은 네트워크 리소스로도 접근할 수 있습니다. 앞의 예시에서, C:\qml\projects 디렉터리가 http://www.some-server.com/qml/projects 으로 호스팅되고 이 URL이 QML 임포트 경로에 추가되었다면, 모듈은 정확히 동일한 방식으로 임포트될 수 있습니다.

파일이 네트워크를 통해 모듈을 임포트할 경우, 해당 모듈이 제공하는 QML 및 JavaScript 리소스에만 접근할 수 있으며, 모듈 내 C++ 플러그인에서 정의된 타입에는 접근할 수 없다는 점에 유의하십시오.

식별된 모듈의 의미론

식별된 모듈에 대해서는 QML 엔진이 다음과 같은 보장을 제공합니다:

• 다른 모듈은 해당 모듈의 네임스페이스 내의 타입을 수정하거나 재정의할 수 없습니다.
• 다른 모듈은 해당 모듈의 네임스페이스에 새로운 타입을 등록할 수 없습니다
• 클라이언트가 유형 이름을 사용하면, 지정된 버전 정보와 임포트 순서에 따라 주어진 유형 정의로 결정론적으로 해결됩니다.

이를 통해 모듈을 사용하는 클라이언트는 모듈에 정의된 객체 유형이 모듈 작성자가 문서화한 대로 동작할 것임을 확신할 수 있습니다.

식별된 모듈에는 다음과 같은 몇 가지 제한 사항이 적용됩니다:

• 식별된 모듈은 QML 임포트 경로에 설치되어야 합니다.
• 모듈 식별자 지시문에 명시된 모듈 식별자는 모듈의 설치 경로와 일치해야 합니다(QML 임포트 경로를 기준으로 하며, 디렉터리 구분자는 마침표로 대체됨).
• 모듈은 해당 타입을 모듈 식별자 타입 네임스페이스에 등록해야 합니다.
• 모듈은 다른 모듈의 네임스페이스에 타입을 등록해서는 안 됩니다.

예를 들어, 식별된 모듈이 $QML_IMPORT_PATH/ExampleModule 에 설치된 경우, 모듈 식별자 지시문은 다음과 같아야 합니다:

module ExampleModule

strict 모듈이 $QML_IMPORT_PATH/com/example/CustomUi 에 설치된 경우, 모듈 식별자 지시어는 다음과 같아야 합니다:

module com.example.CustomUi

그러면 클라이언트는 다음 import 문을 사용하여 위 모듈을 가져올 수 있습니다:

import com.example.CustomUi