식별 모듈

식별된 모듈은 점으로 구분된 식별자 문자열 형식의 URI로 설치되어 QML 엔진에서 식별할 수 있는 모듈로, 해당 모듈이 qmldir 파일에 지정해야 합니다. 이렇게 하면 로컬 파일 시스템에서 모듈의 위치에 관계없이 동일하게 유지되는 고유 식별자를 사용하여 이러한 모듈을 가져올 수 있습니다.

식별된 모듈을 가져올 때는 따옴표로 묶지 않은 식별자가 사용되며 버전 번호는 선택 사항입니다:

import QtQuick
import com.nokia.qml.mymodule 1.0

식별된 모듈을 가져오기 경로에 설치해야 QML 엔진에서 찾을 수 있습니다.

구문론적으로, 점으로 구분된 URI의 각 세그먼트는 올바른 형식의 ECMAScript 식별자 이름이어야 합니다. 예를 들어 세그먼트가 숫자로 시작해서는 안 되며 - (마이너스) 문자를 포함해서는 안 된다는 뜻입니다. URI는 디렉토리 이름으로 번역되므로 라틴 알파벳, 밑줄 및 점의 영숫자 문자로 제한해야 합니다.

로컬로 설치된 식별된 모듈

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

모듈의 qmldir 파일은 가져오기 경로 내의 디렉토리 구조에 있어야 하며, 여기서 식별자의 각 점(".")은 디렉토리 트리의 하위 수준을 반영하는 URI 점으로 구분된 식별자 문자열을 반영합니다. 예를 들어 com.mycompany.mymodule 모듈의 qmldir 파일은 가져오기 경로의 하위 경로 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 파일이 포함되어야 합니다. 예를 들어 모듈 버전 1.0에서 CheckBox, DialogBox 및 Slider 유형을 사용할 수 있게 하려면 qmldir 파일에 다음을 포함해야 합니다:

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

또한 가져오기 경로에서 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

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

module com.example.CustomUi

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

import com.example.CustomUi