QML 문서 디렉터리 가져오기

QML 파일이 포함된 로컬 디렉터리는 별도의 설정이나 구성 없이 가져올 수 있습니다. QML 파일이 포함된 원격 디렉터리도 가져올 수 있지만, 이를 위해서는 디렉터리 목록 파일( qmldir )이 존재해야 합니다. 로컬 디렉터리에는, 해당 디렉터리를 임포트하는 클라이언트에 제공해야 할 유형 이름을 정의하고, 임포터가 사용할 수 있도록 해야 할 자바스크립트 리소스를 지정하기 위해, 선택적으로 디렉터리 목록 qmldir 파일이 포함될 수 있습니다.

Qt는 가져온 디렉터리 내의 모든 파일이 신뢰할 수 있는 출처에서 비롯된 것으로 간주합니다.

로컬 디렉터리 임포트

로컬 파일 시스템에 있는 모든 QML 파일은 디렉터리의 절대 또는 상대 파일 시스템 경로를 참조하는 import 문을 사용하여 로컬 디렉터리를 가져올 수 있으며, 이를 통해 해당 파일은 해당 디렉터리 내에 정의된 객체 유형을 사용할 수 있습니다.

QML Runtime은 가져온 디렉터리에서 선택적 디렉터리 목록 파일( qmldir )을 읽어 QML 및 C++로 정의된 사용 가능한 타입을 식별합니다. qmldir 파일은 QML로 정의된 타입의 이름과 C++로 정의된 타입을 포함하는 플러그인의 경로를 지정합니다.

qmldir 파일이 존재하는 경우, QML 파일은 해당 파일에 지정된 유형 이름으로 제공되며, 그렇지 않은 경우 QML 문서의 파일 이름에서 파생된 유형 이름으로 제공됩니다. 디렉터리에 qmldir 파일이 지정되지 않은 경우, 대문자로 시작하고 ".qml"로 끝나는 파일 이름만 유형으로 노출됩니다.

QML Runtime은 qmldir 파일에 나열된 모든 플러그인을 로드하여 C++에서 노출된 모든 타입을 찾습니다.

디렉터리 임포트의 우선순위는 모든 모듈 임포트보다 낮습니다. 동일한 네임스페이스로 임포트된 모듈과 디렉터리에서 동일한 이름이 정의된 경우, 모듈의 타입만 사용할 수 있습니다.

예시

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

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

main/application.qml 파일은 mycomponents 디렉터리에 대한 상대 경로를 사용하여 해당 디렉터리를 임포트할 수 있으며, 이를 통해 해당 디렉터리 내에 정의된 QML 객체 유형을 사용할 수 있습니다:

import "../mycomponents"

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

이 디렉터리는 한정된 로컬 네임스페이스로 임포트될 수 있으며, 이 경우 디렉터리에 제공된 모든 유형을 사용할 때는 반드시 한정자를 붙여야 합니다:

import "../mycomponents" as MyComponents

MyComponents.DialogBox {
    // ...
}

로컬 디렉터리를 임포트하는 기능은 애플리케이션 내 컴포넌트 세트나 애플리케이션 프로토타이핑과 같은 경우에 편리하지만, 이러한 모듈을 임포트하는 코드는 모듈 디렉터리가 다른 위치로 이동할 경우 관련 ` import ` 문을 반드시 업데이트해야 합니다. 대신 QML 모듈을 사용하면 이 문제를 피할 수 있는데, 설치된 모듈은 파일 시스템 경로 대신 고유한 식별자 문자열로 임포트되기 때문입니다.

암시적 임포트

QML 문서가 위치한 디렉터리는 자동으로 임포트됩니다. "." 이나 이와 유사한 구문을 명시적으로 임포트할 필요가 없습니다.

원격에 위치한 디렉터리

QML 파일이 있는 디렉터리는 해당 디렉터리에 디렉터리 목록 qmldir 파일이 포함되어 있는 경우 원격 위치에서 가져올 수도 있습니다.

예를 들어, 앞의 예시에서 myapp 디렉터리가 "http://www.my-example-server.com"에 호스팅되어 있고, mycomponents 디렉터리에 다음과 같이 정의된 qmldir 파일이 포함되어 있다고 가정해 보겠습니다:

CheckBox CheckBox.qml
DialogBox DialogBox.qml
Slider Slider.qml

이 경우, 원격 mycomponents 디렉터리의 URL을 사용하여 해당 디렉터리를 임포트할 수 있습니다:

import "http://www.my-example-server.com/myapp/mycomponents"

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

파일이 네트워크를 통해 디렉터리를 가져올 때는 해당 디렉터리에 위치한 qmldir 파일에 명시된 QML 및 JavaScript 파일에만 접근할 수 있다는 점에 유의하십시오.

디렉터리 목록 qmldir 파일

디렉터리 목록 qmldir 파일은 모듈 정의 qmldir 파일과는 뚜렷이 다릅니다. 디렉터리 목록 qmldir 파일은 QML 문서 그룹을 빠르고 쉽게 공유할 수 있게 해 주지만, 문서에 정의된 QML 객체 유형이 등록되는 유형 네임스페이스를 정의하지 않으며, 해당 QML 객체 유형의 버전 관리도 지원하지 않습니다.

디렉터리 목록 qmldir 파일의 구문은 다음과 같습니다:

RoundedButton RoundedBtn.qml

internal HighlightedButton HighlightedBtn.qml

MathFunctions mathfuncs.js

로컬 파일 시스템 디렉터리에는 선택적으로 ` qmldir ` 파일을 포함할 수 있습니다. 이를 통해 엔진은 해당 디렉터리를 임포트하는 클라이언트에게 특정 QML 유형만 노출할 수 있습니다. 또한, 디렉터리 내의 자바스크립트 리소스는 ` qmldir ` 파일에 선언되지 않는 한 클라이언트에 노출되지 않습니다.