import 문

import 문 구문

import 문은 클라이언트가 QML 문서 내에서 어떤 모듈, JavaScript 리소스 및 컴포넌트 디렉터리가 사용되는지 엔진에 알릴 수 있게 해줍니다. 문서 내에서 사용할 수 있는 유형은 해당 문서가 어떤 모듈, 리소스 및 디렉터리를 가져오느냐에 따라 달라집니다.

임포트에는 세 가지 유형이 있습니다. 각 임포트 유형마다 구문이 약간 다르며, 유형에 따라 적용되는 의미론도 다릅니다.

모듈(네임스페이스) 임포트

가장 일반적인 임포트 유형은 모듈 임포트입니다. 클라이언트는 QML 객체 유형과 자바스크립트 리소스를 지정된 네임스페이스에 등록하는 QML 모듈을 임포트할 수 있습니다.

모듈 임포트의 일반적인 형식은 다음과 같습니다.

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

• <ModuleIdentifier> 는 점으로 구분된 URI 표기법으로 지정된 식별자로, 모듈이 제공하는 유형 네임스페이스를 고유하게 식별합니다.
• <Version.Number> 는 MajorVersion.MinorVersion 형식의 버전으로, 이 임포트를 통해 어떤 객체 유형 및 자바스크립트 리소스 정의가 사용 가능해질지를 지정합니다. 이를 생략할 수 있으며, 이 경우 모듈의 최신 버전이 임포트됩니다. 또한 마이너 버전만 생략하는 것도 가능합니다. 이 경우 지정된 메이저 버전의 최신 마이너 버전이 임포트됩니다.
• <Qualifier> 는 선택적인 로컬 네임스페이스 식별자로, 지정된 경우 모듈이 제공하는 객체 유형과 자바스크립트 리소스가 해당 네임스페이스에 설치됩니다. 생략할 경우, 모듈이 제공하는 객체 유형과 자바스크립트 리소스는 전역 네임스페이스에 설치됩니다.

자격을 지정하지 않은 모듈 임포트의 예는 다음과 같습니다:

import QtQuick

이 임포트를 사용하면 QtQuick 모듈이 제공하는 모든 타입을 한정자를 명시할 필요 없이 사용할 수 있습니다. 예를 들어, 사각형을 생성하는 클라이언트 코드는 다음과 같습니다:

import QtQuick

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

버전이 지정된 비정규화된 임포트의 예는 다음과 같습니다.

import QtQuick 2.10

이 경우, Qt Quick 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 문서 내에서 고유해야 한다는 점에 유의하십시오.

모듈의 JavaScript 리소스

모듈을 통해 자바스크립트 파일을 제공할 수 있으며, 이를 위해서는 모듈을 지정하는 ` qmldir ` 파일에 식별자 정의를 추가해야 합니다.

예를 들어, projects.MyQMLProject.MyFunctions 모듈이 다음 qmldir 파일로 지정되고 QML 임포트 경로에 설치된 경우:

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

클라이언트 애플리케이션은 모듈을 임포트하고 선언된 리소스와 연관된 식별자를 사용하여 모듈에 선언된 자바스크립트 리소스를 임포트할 수 있습니다:

import QtQuick
import projects.MyQMLProject.MyFunctions

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

모듈이 문서 로컬 네임스페이스로 임포트된 경우, JavaScript 리소스 식별자를 사용하려면 네임스페이스 한정자를 접두사로 붙여야 합니다:

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 엔진은 임포트 경로에서 일치하는 모듈을 검색하여 QML 파일과 QML 모듈 플러그인을 로드합니다. Qt는 임포트 경로 아래의 모든 파일이 신뢰할 수 있는 출처에서 비롯된 것으로 간주합니다.

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

• 해당되는 경우 플랫폼별 번들 경로(예: macOS 또는 Android)
• 애플리케이션 바이너리 디렉터리
• resource 내부의 qrc:/qt-project.org/imports 경로
• resources 내부의 qrc:/qt/Qml 경로(Qt 6.5부터).
• QML2_IMPORT_PATH 환경 변수로 지정된 경로(사용 중단됨)
• QML_IMPORT_PATH 환경 변수로 지정된 경로
• 다음에 의해 지정된 위치 QLibraryInfo::QmlImportsPath

QCoreApplication 에 Qt::AA_PluginApplication 속성이 설정된 경우, 애플리케이션 디렉터리, 환경 변수로 지정된 모든 경로 및 리소스 파일 시스템 외부의 플랫폼별 번들 경로는 기본적으로 생략됩니다.

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

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

디버깅

QML_IMPORT_TRACE 환경 변수는 모듈을 찾거나 로드하는 데 문제가 있을 때 디버깅에 유용할 수 있습니다. 자세한 내용은 모듈 임포트 디버깅을 참조하십시오.