가져오기 문

임포트 문 구문

클라이언트는 임포트 문을 통해 엔진에 QML 문서 내에서 사용되는 모듈, JavaScript 리소스 및 컴포넌트 디렉터리를 알려줄 수 있습니다. 문서 내에서 사용할 수 있는 유형은 문서에서 가져오는 모듈, 리소스 및 디렉터리에 따라 다릅니다.

가져오기에는 세 가지 유형이 있습니다. 각 가져오기 유형에는 약간씩 다른 구문이 있으며 가져오기 유형마다 다른 의미가 적용됩니다.

모듈(네임스페이스) 가져오기

가장 일반적인 가져오기 유형은 모듈 가져오기입니다. 클라이언트는 QML 객체 유형과 JavaScript 리소스를 지정된 네임스페이스에 등록하는 QML 모듈을 가져올 수 있습니다.

모듈 가져오기의 일반적인 형식은 다음과 같습니다:

import <ModuleIdentifier> [<Version.Number>] [as <Qualifier>]

• <ModuleIdentifier> 은 점으로 구분된 URI 표기법으로 지정된 식별자로, 모듈에서 제공하는 유형 네임스페이스를 고유하게 식별합니다.
• <Version.Number> 은 MajorVersion.MinorVersion 형식의 버전으로, 가져오기로 인해 사용할 수 있는 다양한 객체 유형 및 JavaScript 리소스의 정의를 지정합니다. 생략할 수 있으며, 이 경우 최신 버전의 모듈을 가져옵니다. 부 버전만 생략할 수도 있습니다. 그러면 지정된 메이저 버전의 최신 마이너 버전이 가져옵니다.
• <Qualifier> 는 모듈에서 제공하는 객체 유형 및 JavaScript 리소스가 설치될 로컬 네임스페이스 식별자(선택 사항)입니다(제공된 경우). 생략하면 모듈에서 제공하는 객체 유형 및 JavaScript 리소스가 전역 네임스페이스에 설치됩니다.

정규화되지 않은 모듈 가져오기의 예는 다음과 같습니다:

import QtQuick

이 가져오기를 사용하면 한정자를 지정할 필요 없이 QtQuick 모듈에서 제공하는 모든 유형을 사용할 수 있습니다. 예를 들어 직사각형을 만드는 클라이언트 코드는 다음과 같습니다:

import QtQuick

Rectangle {
    width: 200
    height: 100
    color: "red"
}

버전으로 한정되지 않은 가져오기의 예는 다음과 같습니다.

import QtQuick 2.10

이 경우 QtQuick 2.11 이상 또는 6.0과 같은 상위 메이저 버전에 정의된 모든 유형은 파일에서 사용할 수 없습니다.

적격 모듈 가져오기의 예는 다음과 같습니다:

import QtQuick as Quick

이 가져오기를 사용하면 충돌하는 유형 이름을 제공하는 여러 모듈을 동시에 가져올 수 있지만, 한정된 네임스페이스로 가져온 모듈에서 제공하는 유형의 각 사용법은 한정자를 앞에 붙여야 하므로 충돌은 QML 엔진에서 명확하게 해결될 수 있습니다.

한정된 모듈 가져오기를 사용한 후 사각형을 생성하는 클라이언트 코드의 예는 다음과 같습니다:

import QtQuick as Quick

Quick.Rectangle {
    width: 200
    height: 100
    color: "red"
}

적격 가져오기에 대한 자세한 내용은 곧 추가될 적격 로컬 네임스페이스로 가져오기 섹션을 참조하세요.

QML 문서에서 특정 QML 객체 유형을 제공하는 모듈을 가져오지 않고 해당 객체 유형을 사용하려고 시도하면 오류가 발생합니다. 예를 들어 다음 QML 문서는 QtQuick 를 가져오지 않으므로 Rectangle 유형을 사용하려고 시도하면 실패합니다:

Rectangle {
    width: 200
    height: 100
    color: "red"
}

이 경우 엔진은 오류를 발생시키고 파일 로드를 거부합니다.

C++ 모듈 임포트

일반적으로 C++ 유형은 QML_ELEMENT 및 QML_NAMED_ELEMENT() 매크로를 사용하여 선언하고 빌드 시스템을 통해 QML_IMPORT_NAME 및 QML_IMPORT_MAJOR_VERSION을 사용하여 등록합니다. 이렇게 지정된 가져오기 이름과 버전은 해당 유형에 액세스하기 위해 가져올 수 있는 모듈을 구성합니다.

이는 C++에서 자체 QML 객체 유형을 정의하는 클라이언트 애플리케이션에서 가장 일반적입니다.

적격 로컬 네임스페이스로 가져오기

import 문은 선택적으로 as 키워드를 사용하여 유형을 특정 문서-로컬 네임스페이스로 가져오도록 지정할 수 있습니다. 네임스페이스가 지정되면 가져오기에서 사용할 수 있는 유형에 대한 모든 참조 앞에 로컬 네임스페이스 한정자를 붙여야 합니다.

아래에서는 QtQuick 모듈을 네임스페이스 "CoreItems"로 가져옵니다. 이제 QtQuick 모듈의 유형에 대한 모든 참조에는 CoreItems 이름이 접두사로 붙어야 합니다:

import QtQuick as CoreItems

CoreItems.Rectangle {
    width: 100; height: 100

    CoreItems.Text { text: "Hello, world!" }

    // WRONG! No namespace prefix - the Text type won't be found
    Text { text: "Hello, world!" }
}

네임스페이스는 파일 범위 내에서 모듈의 식별자 역할을 합니다. 네임스페이스는 속성, 시그널 및 메서드처럼 외부에서 참조할 수 있는 루트 객체의 속성이 되지는 않습니다.

네임스페이스 가져오기는 이름은 같지만 서로 다른 모듈에 있는 두 개의 QML 유형을 사용해야 하는 경우에 유용합니다. 이 경우 두 모듈을 서로 다른 네임스페이스로 가져와서 코드가 올바른 유형을 참조하는지 확인할 수 있습니다:

import QtQuick as CoreItems
import "../textwidgets" as MyModule

CoreItems.Rectangle {
    width: 100; height: 100

    MyModule.Text { text: "Hello from my custom text item!" }
    CoreItems.Text { text: "Hello from Qt Quick!" }
}

여러 모듈을 전역 네임스페이스로 가져올 수 있는 것과 같은 방식으로 여러 모듈을 동일한 네임스페이스로 가져올 수 있다는 점에 유의하세요. 예를 들어

import QtQuick as Project
import QtMultimedia as Project

Project.Rectangle {
    width: 100; height: 50

    Project.Audio {
        source: "music.wav"
        autoPlay: true
    }
}

디렉토리 가져오기

QML 문서가 포함된 디렉터리를 QML 문서에서 직접 가져올 수도 있습니다. 이렇게 하면 QML 유형을 재사용 가능한 그룹, 즉 파일 시스템의 디렉터리로 분할할 수 있는 간단한 방법이 제공됩니다.

디렉터리 가져오기의 일반적인 형식은 다음과 같습니다:

import "<DirectoryPath>" [as <Qualifier>]

모듈 가져오기와 마찬가지로 디렉터리 가져오기에도 <Qualifier> 에 대한 유사한 의미가 적용되며, 이 주제에 대한 자세한 내용은 이전 섹션의 적격 로컬 네임스페이스로 가져오기를 참조하세요.

디렉터리 가져오기에 대한 자세한 내용은 디렉터리 가져오기에 대한 심층 문서를 참조하세요.

JavaScript 리소스 가져오기

JavaScript 리소스는 QML 문서에서 직접 가져올 수 있습니다. 모든 JavaScript 리소스에는 액세스하는 식별자가 있어야 합니다.

JavaScript 리소스 가져오기의 일반적인 형식은 다음과 같습니다:

import "<JavaScriptFile>" as <Identifier>

모듈 가져오기에 적용할 수 있는 로컬 네임스페이스 한정자와는 달리 <Identifier> 는 QML 문서 내에서 고유해야 합니다.

모듈에서 자바스크립트 리소스 가져오기

모듈을 지정하는 qmldir 파일에 식별자 정의를 추가하여 모듈에서 자바스크립트 파일을 제공할 수 있습니다.

예를 들어 projects.MyQMLProject.MyFunctions 모듈을 다음 qmldir 파일로 지정하고 QML 가져오기 경로에 설치하는 경우:

module projects.MyQMLProject.MyFunctions
SystemFunctions 1.0 SystemFunctions.js
UserFunctions 1.0 UserFunctions.js

클라이언트 애플리케이션은 모듈을 가져오고 선언된 리소스와 연결된 식별자를 사용하여 모듈에 선언된 JavaScript 리소스를 가져올 수 있습니다:

import QtQuick
import projects.MyQMLProject.MyFunctions

Item {
    Component.onCompleted: { SystemFunctions.cleanUp(); }
}

모듈을 문서-로컬 네임스페이스로 가져온 경우, 자바스크립트 리소스 식별자 앞에 네임스페이스 한정자를 붙여야 사용할 수 있습니다:

import QtQuick
import projects.MyQMLProject.MyFunctions as MyFuncs
import org.example.Functions as TheirFuncs

Item {
    Component.onCompleted: {
        MyFuncs.SystemFunctions.cleanUp();
        TheirFuncs.SystemFunctions.shutdown();
    }
}

추가 정보

JavaScript 리소스에 대한 자세한 내용은 QML에서 JavaScript 리소스 정의하기 문서를 참조하고, JavaScript 리소스를 가져오는 방법과 JavaScript 리소스 내에서 임포트를 사용하는 방법에 대한 자세한 내용은 QML에서 JavaScript 리소스 가져오기에 대한 심층 문서를 참조하세요.

QML 가져오기 경로

식별된 모듈을 가져오면 QML 엔진은 가져오기 경로에서 일치하는 모듈을 검색합니다.

QQmlEngine::importPathList()에서 반환되는 이 가져오기 경로는 엔진에서 검색할 기본 위치를 정의합니다. 기본적으로 이 목록에는 다음이 포함됩니다:

• 현재 파일의 디렉토리
• 에 의해 지정된 위치 QLibraryInfo::QmlImportsPath
• QML_IMPORT_PATH 환경 변수에 의해 지정된 경로
• 리소스 내부의 qrc:/qt-project.org/imports 경로.
• 리소스 내부의 qrc:/qt/qml 경로(Qt 6.5 이후).

QQmlEngine::addImportPath() 또는 QML_IMPORT_PATH 환경 변수를 통해 추가 임포트 경로를 추가할 수 있습니다. qml 도구를 실행할 때 -I 옵션을 사용하여 가져오기 경로를 추가할 수도 있습니다.

QML_IMPORT_PATH 환경 변수에서 경로 구분 기호를 사용하여 여러 가져오기 경로를 연결하여 지정할 수 있습니다. Windows에서는 경로 구분 기호가 세미콜론(;)이고, 다른 플랫폼에서는 콜론(:)입니다. 즉, 리소스 경로나 URL은 콜론 자체가 포함되어 있으므로 QML_IMPORT_PATH에 지정할 수 없습니다. 그러나 프로그래밍 방식으로 QQmlEngine::addImportPath()를 호출하여 리소스 경로 및 URL을 추가할 수 있습니다.

디버깅

QML_IMPORT_TRACE 환경 변수는 모듈을 찾고 로드하는 데 문제가 있을 때 디버깅에 유용할 수 있습니다. 자세한 내용은 모듈 가져오기 디버깅을 참조하세요.