Loader QML Type

URL 또는 컴포넌트에서 서브트리를 동적으로 불러올 수 있습니다. 더 보기...

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

속성

• active : bool
• asynchronous : bool
• item : QtObject
• progress : real
• source : url
• sourceComponent : Component
• status : enumeration

신호

• loaded()

방법

• void setSource(url source, var properties)

상세 설명

Loader는 QML 컴포넌트를 동적으로 로드하는 데 사용됩니다.

Loader는 QML 파일( source 속성을 사용)이나 Component 객체( sourceComponent 속성을 사용)를 로드할 수 있습니다. 이는 컴포넌트가 필요할 때까지 생성을 지연시키는 데 유용합니다. 예를 들어, 컴포넌트를 필요에 따라 동적으로 생성해야 하거나, 성능상의 이유로 불필요한 컴포넌트 생성을 피해야 할 때 유용합니다.

다음은 MouseArea 를 클릭했을 때 "Page1.qml"을 컴포넌트로 로드하는 Loader입니다:

import QtQuick

Item {
    width: 200; height: 200

    Loader { id: pageLoader }

    MouseArea {
        anchors.fill: parent
        onClicked: pageLoader.source = "Page1.qml"
    }
}

item 속성을 사용하여 로드된 객체에 접근할 수 있습니다.

source 이나 sourceComponent 가 변경되면, 이전에 인스턴스화된 항목은 모두 소멸됩니다. source 를 빈 문자열로 설정하거나 sourceComponent 를 undefined 로 설정하면 현재 로드된 객체가 소멸되어 리소스가 해제되고 로더가 비워집니다.

Loader의 크기 조정 동작

Loader를 사용하여 시각적 유형을 로드할 때, Loader는 다음과 같은 크기 조정 규칙을 적용합니다:

• Loader에 명시적인 크기가 지정되지 않은 경우, 컴포넌트가 로드되면 Loader는 로드된 항목의 크기에 맞춰 자동으로 크기가 조정됩니다.
• 너비, 높이 설정 또는 고정(anchoring)을 통해 Loader의 크기가 명시적으로 지정된 경우, 로드된 항목의 크기가 Loader의 크기에 맞춰 조정됩니다.

두 경우 모두 항목과 로더의 크기는 동일합니다. 이를 통해 로더에 정렬하는 것이 로드된 항목에 정렬하는 것과 동일하게 처리됩니다.

import QtQuick

Item {
  width: 200; height: 200

  Loader {
    // Explicitly set the size of the
    // Loader to the parent item's size
    anchors.fill: parent
    sourceComponent: rect
  }

  Component {
    id: rect
    Rectangle {
      width: 50
      height: 50
      color: "red"
      }
  }
}

import QtQuick

Item {
  width: 200; height: 200

  Loader {
    // position the Loader in the center
    // of the parent
    anchors.centerIn: parent
    sourceComponent: rect
  }

  Component {
      id: rect
      Rectangle {
          width: 50
          height: 50
          color: "red"
      }
  }
}

소스 컴포넌트가 Item 유형이 아닌 경우, Loader는 특별한 크기 조정 규칙을 적용하지 않습니다.

로드된 객체로부터 신호 수신

로드된 객체에서 발신되는 모든 신호는 ` Connections ` 유형을 사용하여 수신할 수 있습니다. 예를 들어, 다음 ` application.qml `은 ` MyItem.qml`을 로드하며, ` Connections ` 객체를 통해 로드된 항목의 ` message ` 신호를 수신할 수 있습니다:

import QtQuick

Item {
    width: 100; height: 100

    Loader {
       id: myLoader
       source: "MyItem.qml"
    }

    Connections {
        target: myLoader.item
        function onMessage(msg) { console.log(msg) }
    }
}

import QtQuick

Rectangle {
   id: myItem
   signal message(string msg)

   width: 100; height: 100

   MouseArea {
       anchors.fill: parent
       onClicked: myItem.message("clicked!")
   }
}

포커스 및 키 이벤트

Loader는 포커스 범위입니다. 자식 요소 중 어느 하나라도 활성 포커스를 얻으려면 Loader의 focus 속성을 true 로 설정해야 합니다. (자세한 내용은 Qt Quick 의 ‘키보드 포커스’를 참조하십시오.) 로드된 항목에서 수신된 모든 키 이벤트도 Loader로 전파되지 않도록 accepted 로 처리해야 합니다.

예를 들어, 다음 ` application.qml ` 코드는 ` MouseArea `을 클릭하면 ` KeyReader.qml `을 로드합니다. 여기서 ` focus ` 속성이 `Loader`뿐만 아니라 동적으로 로드된 객체의 ` Item `에 대해서도 ` true `로 설정되어 있음을 확인하십시오:

import QtQuick

Rectangle {
    width: 200; height: 200

    Loader {
        id: loader
        focus: true
    }

    MouseArea {
        anchors.fill: parent
        onClicked: {
            loader.source = "KeyReader.qml"
        }
    }

    Keys.onPressed: (event)=> {
        console.log("Captured:",
                    event.text);
    }
}

import QtQuick

Item {
    Item {
        focus: true
        Keys.onPressed: (event)=> {
            console.log("KeyReader captured:",
                        event.text);
            event.accepted = true;
        }
    }
}

KeyReader.qml 가 로드되면 키 이벤트를 수신하고, 이벤트가 상위 Rectangle 로 전파되지 않도록 event.accepted 를 true 로 설정합니다.

QtQuick 2.0 덕분에 Loader는 비시각적 컴포넌트도 로드할 수 있습니다.

뷰 델리게이트 내에서 Loader 사용하기

경우에 따라 델리게이트 로딩 성능을 향상시키기 위해 뷰 델리게이트 내에서 Loader를 사용하고자 할 수 있습니다. 이는 대부분의 경우 잘 작동하지만, 컴포넌트의 creation context 과 관련하여 주의해야 할 중요한 문제가 하나 있습니다.

다음 예제에서, ListView 가 delegateComponent 의 컨텍스트에 삽입한 index 컨텍스트 속성은 Text에서 접근할 수 없습니다. Loader는 인스턴스화할 때 myComponent 의 생성 컨텍스트를 부모 컨텍스트로 사용하며, index 는 해당 컨텍스트 체인 내의 어떤 요소도 참조하지 않기 때문입니다.

Item {
    width: 400
    height: 400

    Component {
        id: myComponent
        Text { text: index }    //fails
    }

    ListView {
        anchors.fill: parent
        model: 5
        delegate: Component {
            id: delegateComponent
            Loader {
                sourceComponent: myComponent
            }
        }
    }
}

이러한 상황에서는 컴포넌트를 인라인으로 이동하거나,

        delegate: Component {
            Loader {
                sourceComponent: Component {
                    Text { text: index }    //okay
                }
            }
        }

별도의 파일로 분리하거나,

        delegate: Component {
            Loader {
                source: "MyComponent.qml" //okay
            }
        }

또는 필요한 정보를 Loader의 속성으로 명시적으로 설정할 수 있습니다(Loader는 로드 중인 컴포넌트의 컨텍스트 객체로 자신을 설정하기 때문에 이 방법이 작동합니다).

Item {
    width: 400
    height: 400

    Component {
        id: myComponent
        Text { text: modelIndex }    //okay
    }

    ListView {
        anchors.fill: parent
        model: 5
        delegate: Component {
            Loader {
                property int modelIndex: index
                sourceComponent: myComponent
            }
        }
    }
}

Dynamic Object Creation도 참조하십시오 .

속성 문서

active : bool

이 속성은 로더(Loader)가 현재 활성화된 경우 ` true `입니다. 이 속성의 기본값은 ` true`입니다.

로더가 비활성 상태인 경우, ` source ` 또는 ` sourceComponent `을 변경하더라도 로더가 활성화될 때까지는 해당 항목이 인스턴스화되지 않습니다.

값을 inactive로 설정하면 로더에 의해 로드된 모든 item 가 해제되지만, source 나 sourceComponent 에는 영향을 미치지 않습니다.

비활성 로더의 status 는 항상 Null 입니다.

source 및 sourceComponent항목도 참조하십시오 .

asynchronous : bool

이 속성은 컴포넌트가 비동기적으로 인스턴스화될지 여부를 결정합니다. 기본값은 ‘ false ’입니다.

source 속성과 함께 사용하면 로딩 및 컴파일도 백그라운드 스레드에서 수행됩니다.

비동기 로딩은 여러 프레임에 걸쳐 컴포넌트가 선언한 객체를 생성하며, 애니메이션에서 발생하는 오류의 가능성을 줄여줍니다. 비동기 로딩 시 상태는 Loader.Loading으로 변경됩니다. 컴포넌트 전체가 생성되면 ` item `가 사용 가능해지며, 상태는 Loader.Ready로 변경됩니다.

비동기 로딩이 진행 중일 때 이 속성의 값을 false 로 변경하면 즉시 동기식으로 완료됩니다. 이를 통해 비동기 로딩을 시작한 후, 비동기 로딩이 완료되기 전에 Loader 콘텐츠에 액세스해야 하는 경우 강제로 완료를 유도할 수 있습니다.

항목이 점진적으로 로딩되는 것을 방지하려면 visible 를 적절히 설정하십시오. 예:

Loader {
    source: "mycomponent.qml"
    asynchronous: true
    visible: status == Loader.Ready
}

이 속성은 객체 인스턴스화에만 영향을 미치며, 네트워크를 통해 컴포넌트를 비동기적으로 로딩하는 것과는 무관합니다.

item : QtObject [read-only]

이 속성은 현재 로드된 최상위 객체를 보관합니다.

QtQuick 2.0 부터 Loader는 모든 객체 유형을 로드할 수 있습니다.

progress : real [read-only]

이 속성은 네트워크에서 QML 데이터를 불러오는 진행 상황을 0.0(아직 아무것도 불러오지 않음)부터 1.0(완료됨)까지 나타냅니다. 대부분의 QML 파일은 크기가 매우 작기 때문에, 이 값은 0에서 1로 빠르게 변합니다.

status도 참조하십시오 .

source : url

이 속성은 인스턴스화할 QML 컴포넌트의 URL을 저장합니다.

QtQuick 2.0 부터 Loader는 Item 유형에 국한되지 않고 모든 유형의 객체를 로드할 수 있습니다.

현재 로드된 객체를 언로드하려면 이 속성을 빈 문자열로 설정하거나, ` sourceComponent `을 ` undefined`로 설정하십시오. ` source `을 새로운 URL로 설정해도 이전 URL로 생성된 항목이 언로드됩니다.

sourceComponent, status 및 progress도 참조하십시오 .

sourceComponent : Component

이 속성은 인스턴스화할 Component 객체를 포함합니다.

Item {
    Component {
        id: redSquare
        Rectangle { color: "red"; width: 10; height: 10 }
    }

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

현재 로드된 객체를 언로드하려면 이 속성을 undefined 로 설정하십시오.

QtQuick 2.0 덕분에 Loader는 Item 유형에 국한되지 않고 모든 유형의 객체를 로드할 수 있습니다.

source 및 progress도 참조하십시오 .

status : enumeration [read-only]

이 속성은 QML 로딩 상태를 나타냅니다. 다음 중 하나일 수 있습니다:

• Loader.Null - 로더가 비활성화되었거나 QML 소스가 설정되지 않은 경우
• Loader.Ready - QML 소스가 로드되었습니다
• Loader.Loading - 현재 QML 소스 파일이 로드 중입니다
• Loader.Error - QML 소스를 로드하는 동안 오류가 발생했습니다

이 상태를 사용하여 업데이트를 제공하거나 상태 변경에 대응할 수 있습니다. 예를 들어 다음과 같은 작업을 수행할 수 있습니다:

• 상태 변경을 트리거합니다:

  State { name: 'loaded'; when: loader.status == Loader.Ready }

• onStatusChanged 신호 핸들러를 구현:

  Loader {
      id: loader
      onStatusChanged: if (loader.status == Loader.Ready) console.log('Loaded')
  }

• 상태 값에 바인딩:

  Text { text: loader.status == Loader.Ready ? 'Loaded' : 'Not loaded' }

소스가 로컬 파일인 경우, 상태는 처음에 Ready(또는 Error)가 됩니다. 이 경우 onStatusChanged 신호는 발생하지 않지만, onLoaded는 여전히 호출됩니다.

progress도 참조하십시오 .

신호 문서

loaded()

이 신호는 status 가 Loader.Ready 로 변경되거나, 초기 로드가 성공적으로 완료되었을 때 발생합니다.

메서드 문서

void setSource(url source, var properties)

지정된 source 컴포넌트의 객체 인스턴스를 생성하며, 이 인스턴스는 지정된 properties 를 갖게 됩니다. properties 인수는 선택 사항입니다. 로딩 및 인스턴스화가 완료되면 item 속성을 통해 해당 인스턴스에 접근할 수 있습니다.

이 함수가 호출될 당시 ‘ active ’ 속성이 ‘ false ’인 경우, 지정된 ‘ source ’ 컴포넌트는 로드되지 않지만 ‘ source ’ 및 초기 ‘ properties ’ 값은 캐시됩니다. 로더가 ‘ active ’ 상태가 되면, ‘ properties ’가 설정된 ‘ source ’ 컴포넌트의 인스턴스가 생성됩니다.

이러한 방식으로 컴포넌트 인스턴스의 초기 속성 값을 설정해도 관련 Behavior는 트리거되지 않습니다.

이 함수를 호출한 후, 로더( active)를 설정하기 전에 ` source ` 또는 ` sourceComponent `가 변경되면 캐시된 ` properties `가 지워진다는 점에 유의하십시오.

예:

// ExampleComponent.qml
import QtQuick 2.0
Rectangle {
    id: rect
    color: "red"
    width: 10
    height: 10

    Behavior on color {
        NumberAnimation {
            target: rect
            property: "width"
            to: (rect.width + 20)
            duration: 0
        }
    }
}

// example.qml
import QtQuick 2.0
Item {
    Loader {
        id: squareLoader
        onLoaded: console.log(squareLoader.item.width);
        // prints [10], not [30]
    }

    Component.onCompleted: {
        squareLoader.setSource("ExampleComponent.qml",
                             { "color": "blue" });
        // will trigger the onLoaded code when complete.
    }
}

source 및 active도 참조하십시오 .