Component QML Type

QML 컴포넌트 정의를 캡슐화합니다. 더 보기...

• 상속된 멤버를 포함한 모든 멤버 목록

속성

• progress : real
• status : enumeration
• url : url

첨부된 신호

• completed()
• destruction()

방법

• QtObject createObject(QtObject parent, var properties)
• string errorString()
• var incubateObject(QtObject parent, var properties, enumeration mode)

상세 설명

컴포넌트는 명확하게 정의된 인터페이스를 가진 재사용 가능하고 캡슐화된 QML 유형입니다.

컴포넌트는 대개 컴포넌트 파일, 즉 .qml 파일로 정의됩니다. Component 유형을 사용하면 QML 구성 요소를 별도의 QML 파일로 정의하는 대신 QML 문서 내에서 인라인으로 정의할 수 있습니다. 이는 QML 파일 내에서 작은 구성 요소를 재사용하거나, 파일 내의 다른 QML 구성 요소와 논리적으로 연관된 구성 요소를 정의하는 데 유용할 수 있습니다.

예를 들어, 다음은 여러 Loader 객체에서 사용되는 컴포넌트입니다. 이 컴포넌트는 단일 항목인 Rectangle 을 포함하고 있습니다:

import QtQuick

Item {
    width: 100; height: 100

    Component {
        id: redSquare

        Rectangle {
            color: "red"
            width: 10
            height: 10
        }
    }

    Loader { sourceComponent: redSquare }
    Loader { sourceComponent: redSquare; x: 20 }
}

Rectangle 자체는 자동으로 렌더링되어 표시되지만, 위의 사각형은 Component 내부에 정의되어 있기 때문에 자동으로 렌더링되지 않는다는 점에 유의하십시오. 이 컴포넌트는 마치 별도의 QML 파일에 정의된 것처럼 내부의 QML 유형을 캡슐화하며, 요청(이 경우 두 개의 Loader 객체에 의해)이 있을 때까지 로드되지 않습니다. Component는 Item을 상속받지 않으므로, 이 컴포넌트에 어떤 요소도 고정할 수 없습니다.

Component 를 정의하는 것은 QML 문서를 정의하는 것과 유사합니다. QML 문서는 해당 컴포넌트의 동작과 속성을 정의하는 단일 최상위 항목을 가지며, 그 최상위 항목 외부에서는 속성이나 동작을 정의할 수 없습니다. 마찬가지로, Component 정의에는 단일 최상위 항목(위 예제에서는 Rectangle)이 포함되며, id (위 예제에서는 redSquare)를 제외하고는 이 항목 외부에 데이터를 정의할 수 없습니다.

Component 유형은 일반적으로 뷰에 그래픽 컴포넌트를 제공하는 데 사용됩니다. 예를 들어, ListView::delegate 속성은 각 목록 항목이 어떻게 표시될지 지정하기 위해 Component 를 필요로 합니다.

Component Qt.createComponent()을 사용하여 객체를 동적으로 생성할 수도 있습니다.

Component인라인 컴포넌트(s)는 완전히 새로운 파일을 추가하지 않고도 해당 유형의 인스턴스만 필요한 경우 유형을 선언하는 데 유용합니다. 그러나 이 유형에 이름을 지정할 수 없으므로, 이를 사용하여 속성을 선언하거나 유형 어노테이션에서 사용할 수는 없습니다. 이러한 기능이 필요한 경우 인라인 컴포넌트를 사용하는 것이 좋습니다.

생성 컨텍스트

컴포넌트의 생성 컨텍스트는 해당 컴포넌트가 선언된 컨텍스트와 일치합니다. 이 컨텍스트는 ListView 이나 Loader와 같은 객체에 의해 컴포넌트가 인스턴스화될 때 부모 컨텍스트( 컨텍스트 계층 구조 형성)로 사용됩니다.

다음 예제에서 comp1 는 MyItem.qml의 루트 컨텍스트 내에서 생성되며, 이 컴포넌트로부터 인스턴스화된 모든 객체는 internalSettings.color 와 같이 해당 컨텍스트 내의 ID 및 속성에 접근할 수 있습니다. comp1 가 다른 컨텍스트(아래 main.qml과 같이)에서 ListView 델리게이트로 사용될 때도, 생성 컨텍스트의 속성(다른 경우라면 외부 사용자에게는 비공개로 처리될 속성)에 계속 접근할 수 있습니다.

Item {
    property Component mycomponent: comp1

    QtObject {
        id: internalSettings
        property color color: "green"
    }

    Component {
        id: comp1
        Rectangle { color: internalSettings.color; width: 400; height: 50 }
    }
}

ListView {
    width: 400; height: 400
    model: 5
    delegate: myItem.mycomponent    //will create green Rectangles

    MyItem { id: myItem }
}

생성 컨텍스트의 수명은 생성된 모든 객체의 수명보다 길어야 합니다. 자세한 내용은 ‘동적으로 생성된 객체 유지 관리’를 참조하십시오.

속성 문서

progress : real [read-only]

컴포넌트 로딩 진행 상황은 0.0(아직 로딩되지 않음)부터 1.0(완료)까지 표시됩니다.

status : enumeration [read-only]

이 속성은 컴포넌트 로딩 상태를 나타냅니다. 상태는 다음 중 하나일 수 있습니다:

url : url [read-only]

컴포넌트 URL. 이 URL은 해당 컴포넌트를 생성하는 데 사용된 URL입니다.

첨부된 신호 문서

[attached] completed()

객체가 인스턴스화된 후에 발생합니다. 이 신호는 전체 QML 환경이 구축된 후, 시작 시 스크립트 코드를 실행하는 데 사용할 수 있습니다.

onCompleted 신호 핸들러는 어떤 객체에서든 선언할 수 있습니다. 핸들러가 실행되는 순서는 정의되지 않습니다.

Rectangle {
    Component.onCompleted: console.log("Completed Running!")
    Rectangle {
        Component.onCompleted: console.log("Nested Completed Running!")
    }
}

[attached] destruction()

객체가 소멸되기 시작할 때 발생합니다. 이 신호는 ` completed()` 신호에 대한 응답으로 수행된 작업이나 애플리케이션 내의 기타 명령형 코드를 되돌리는 데 사용할 수 있습니다.

onDestruction 신호 핸들러는 어떤 객체에서든 선언할 수 있습니다. 핸들러가 실행되는 순서는 정의되지 않습니다.

Rectangle {
    Component.onDestruction: console.log("Destruction Beginning!")
    Rectangle {
        Component.onDestruction: console.log("Nested Destruction Beginning!")
    }
}

참조 Qt Qml.

메서드 문서

QtObject createObject(QtObject parent, var properties)

지정된 ` parent ` 및 ` properties`을 갖는 이 컴포넌트의 객체 인스턴스를 생성하여 반환합니다. ` properties ` 인수는 선택 사항입니다. 객체 생성에 실패하면 null을 반환합니다.

객체는 컴포넌트가 생성된 것과 동일한 컨텍스트에서 생성됩니다. 이 함수는 QML에서 생성되지 않은 컴포넌트에 대해 호출될 경우 항상 null을 반환합니다.

부모를 설정하지 않고 객체를 생성하려면 parent 값으로 null 을 지정하십시오. 반환된 객체를 표시하려면 유효한 parent 값을 제공하거나 반환된 객체의 parent 속성을 설정해야 합니다. 그렇지 않으면 객체가 표시되지 않습니다.

createObject()에 parent 가 제공되지 않은 경우, 반환된 객체가 가비지 컬렉터에 의해 소멸되지 않도록 해당 객체에 대한 참조를 유지해야 합니다. 이는 나중에 Item::parent 가 설정되든 그렇지 않든 상관없이 적용되는 사항입니다. Item 부모를 설정한다고 해서 객체의 소유권이 변경되는 것은 아니기 때문입니다. 변경되는 것은 그래픽 부모뿐입니다.

이 메서드는 생성된 객체의 초기 속성 값 맵을 지정하는 선택적 properties 인자를 받습니다. 이러한 값들은 객체 생성이 완료되기 전에 적용됩니다. 이는 객체 생성 후 속성 값을 설정하는 것보다 효율적이며, 특히 대량의 속성 값 세트가 정의된 경우에 유용합니다. 또한 객체가 생성되기 전에 ( Qt.binding 을 사용하여) 속성 바인딩을 설정할 수 있게 해줍니다.

properties 인수는 속성-값 항목의 맵 형태로 지정됩니다. 예를 들어, 아래 코드는 x 과 y 의 초기 값을 각각 100과 100으로 설정하여 객체를 생성합니다.

const component = Qt.createComponent("Button.qml");
if (component.status === Component.Ready) {
    component.createObject(parent, { x: 100, y: 100 });
}

동적으로 생성된 인스턴스는 ` destroy() ` 메서드를 사용하여 삭제할 수 있습니다. 자세한 내용은 ‘JavaScript를 통한 동적 QML 객체 생성’을 참조하십시오.

incubateObject()항목도 참조하십시오 .

string errorString()

오류에 대한 사람이 읽기 쉬운 설명을 반환합니다.

이 문자열에는 각 오류의 파일, 위치 및 설명이 포함됩니다. 여러 오류가 있는 경우, 각 오류는 줄바꿈 문자로 구분됩니다.

오류가 없는 경우, 빈 문자열이 반환됩니다.

var incubateObject(QtObject parent, var properties, enumeration mode)

이 컴포넌트의 인스턴스를 위한 인큐베이터를 생성합니다. 인큐베이터를 사용하면 새로운 컴포넌트 인스턴스를 비동기적으로 생성할 수 있으며, UI가 멈추는 현상을 방지할 수 있습니다.

parent 인수는 생성된 인스턴스의 부모를 지정합니다. 이 매개변수를 생략하거나 null을 전달하면 부모가 없는 객체가 생성됩니다. 이 경우, 생성된 객체가 가비지 컬렉터에 의해 파기되지 않도록 해당 객체에 대한 참조를 반드시 유지해야 합니다.

properties 인수는 생성되는 객체의 생성 과정에서 설정될 속성-값 항목의 맵으로 지정됩니다. mode 는 Qt.Synchronous 또는 Qt.Asynchronous일 수 있으며, 인스턴스가 동기적으로 생성될지 비동기적으로 생성될지를 제어합니다. 기본값은 비동기입니다. 일부 상황에서는 Qt.Synchronous가 지정되었더라도 인큐베이터가 객체를 비동기적으로 생성할 수 있습니다. 이는 incubateObject()를 호출하는 컴포넌트 자체가 비동기적으로 생성되고 있는 경우에 발생합니다.

세 개의 인자 모두 선택 사항입니다.

성공하면 이 메서드는 인큐베이터를 반환하고, 그렇지 않으면 null을 반환합니다. 인큐베이터는 다음과 같은 속성을 가집니다:

• status - 인큐베이터의 상태. 유효한 값은 Component.Ready, Component.Loading 및 Component.Error입니다.
• object - 생성된 객체 인스턴스. 인큐베이터가 Ready 상태가 되어야만 사용할 수 있습니다.
• onStatusChanged - 상태가 변경될 때 호출될 콜백 함수를 지정합니다. 상태는 콜백 함수의 매개변수로 전달됩니다.
• forceCompletion() - 인큐베이션을 동기식으로 완료하기 위한 호출입니다.

다음 예제는 인큐베이터 사용 방법을 보여줍니다:

const component = Qt.createComponent("Button.qml");

const incubator = component.incubateObject(parent, { x: 10, y: 10 });
if (incubator.status !== Component.Ready) {
    incubator.onStatusChanged = function(status) {
        if (status === Component.Ready) {
            print("Object", incubator.object, "is now ready!");
        }
    };
} else {
    print("Object", incubator.object, "is ready immediately!");
}

동적으로 생성된 인스턴스는 ` destroy() ` 메서드를 사용하여 삭제할 수 있습니다. 자세한 내용은 'JavaScript를 통한 동적 QML 객체 생성'을 참조하십시오.

createObject()도 참조하십시오 .