Back to Qt.io
Contact Us Blog Download Qt

Loader QML Type

URL 또는 컴포넌트에서 하위 트리를 동적으로 로드할 수 있습니다. 더 보기...

Import Statement: import QtQuick
Inherits:

Item

속성

신호

방법

  • object setSource(url source, object properties)

상세 설명

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

로더는 QML 파일( source 속성 사용) 또는 Component 객체( sourceComponent 속성 사용)를 로드할 수 있습니다. 컴포넌트를 필요에 따라 생성해야 하거나 성능상의 이유로 불필요하게 생성해서는 안 되는 경우와 같이 필요할 때까지 컴포넌트 생성을 지연시키는 데 유용합니다.

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

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 로 설정하면 현재 로드된 객체가 파괴되어 리소스가 확보되고 로더가 비어 있게 됩니다.

로더 크기 조정 동작

시각적 유형을 로드하는 데 사용되는 경우 로더는 다음과 같은 크기 조정 규칙을 적용합니다:

  • 로더에 명시적인 크기를 지정하지 않으면 컴포넌트가 로드되면 로더는 로드된 항목의 크기에 맞게 자동으로 크기가 조정됩니다.
  • 너비, 높이를 설정하거나 앵커링하여 로더의 크기를 명시적으로 지정한 경우 로드된 항목의 크기가 로더의 크기에 맞게 조정됩니다.

두 시나리오 모두 항목과 로더의 크기는 동일합니다. 이렇게 하면 로더에 앵커링하는 것이 로드된 항목에 앵커링하는 것과 동일합니다.

sizeloader.qmlsizeitem.qml
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"
      }
  }
}
빨간색 직사각형은 루트 항목의 크기에 맞게 크기가 조정됩니다.빨간색 직사각형은 루트 항목을 중심으로 50x50이 됩니다.

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

로드된 객체에서 신호 수신

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

application.qmlMyItem.qml
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!")
   }
}

또는 MyItem.qml 은 로더의 범위 내에서 로드되므로 로더 또는 그 부모 Item 에 정의된 함수를 직접 호출할 수도 있습니다.

포커스 및 주요 이벤트

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

예를 들어 다음 application.qml 은 MouseArea 을 클릭하면 KeyReader.qml 을 로드합니다. focus 속성은 로더의 경우 true, 동적으로 로드된 객체의 경우 Item 로 설정되어 있음을 알 수 있습니다:

application.qmlKeyReader.qml
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 이 로드되면 키 이벤트를 수락하고 event.accepted 을 true 으로 설정하여 이벤트가 부모 Rectangle 로 전파되지 않도록 합니다.

QtQuick 2.0 이후 로더는 비시각적 컴포넌트도 로드할 수 있습니다.

뷰 델리게이트 내에서 로더 사용

경우에 따라 델리게이트 로딩 성능을 개선하기 위해 뷰 델리게이트 내에서 로더를 사용하고 싶을 수 있습니다. 이 방법은 대부분의 경우 잘 작동하지만 컴포넌트의 creation context 와 관련하여 주의해야 할 중요한 문제가 하나 있습니다.

다음 예제에서 ListView 이 delegateComponent 의 컨텍스트에 삽입한 index 컨텍스트 속성은 로더가 인스턴스화할 때 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
            }
        }

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

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

로더가 현재 활성화된 경우 이 속성은 true 입니다. 이 프로퍼티의 기본값은 true 입니다.

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

값을 비활성으로 설정하면 로더가 로드한 item 은 해제되지만 source 또는 sourceComponent 에는 영향을 미치지 않습니다.

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

source 및 sourceComponent도 참조하십시오 .


asynchronous : bool

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

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

비동기적으로 로드하면 컴포넌트가 선언한 객체가 여러 프레임에 걸쳐 생성되며 애니메이션에서 글리치가 발생할 가능성이 줄어듭니다. 비동기 로딩 시 상태는 Loader.Loading으로 변경됩니다. 전체 컴포넌트가 생성되면 item 을 사용할 수 있고 상태는 Loader.Ready로 변경됩니다.

비동기 로드가 진행 중일 때 이 속성 값을 false 으로 변경하면 즉시 동기식으로 완료됩니다. 이렇게 하면 비동기 로드를 시작한 다음 비동기 로드가 완료되기 전에 로더 콘텐츠에 액세스해야 하는 경우 강제로 완료할 수 있습니다.

항목이 점진적으로 로드되는 것을 방지하려면 visible 을 적절하게 설정하세요.

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

이 속성은 객체 인스턴스화에만 영향을 주며 네트워크를 통한 컴포넌트 비동기 로딩과는 관련이 없습니다.


item : QtObject [read-only]

이 프로퍼티는 현재 로드된 최상위 객체를 보유합니다.

QtQuick 2.0 이후 로더는 모든 객체 유형을 로드할 수 있습니다.


progress : real [read-only]

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

status 를참조하세요 .


source : url

이 프로퍼티는 인스턴스화할 QML 컴포넌트의 URL을 보유합니다.

QtQuick 2.0 이후 로더는 모든 유형의 객체를 로드할 수 있으며, 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, 로더는 모든 유형의 객체를 로드할 수 있으며 항목 유형으로 제한되지 않습니다.

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' }

소스가 로컬 파일인 경우 상태는 처음에 준비됨(또는 오류)이 됩니다. 이 경우 onStatusChanged 신호는 없지만 onLoaded는 계속 호출됩니다.

progress 를참조하세요 .


신호 문서

loaded()

이 신호는 status 이 Loader.Ready 이 될 때 또는 초기 로드가 성공할 때 발생합니다.

참고: 해당 핸들러는 onLoaded 입니다.


메서드 문서

object setSource(url source, object properties)

주어진 source 컴포넌트의 객체 인스턴스를 생성하여 properties 을 갖도록 합니다. properties 인수는 선택 사항입니다. 로딩 및 인스턴스화가 완료되면 item 속성을 통해 인스턴스에 액세스할 수 있습니다.

이 함수가 호출될 때 active 속성이 false 인 경우 지정된 source 컴포넌트는 로드되지 않고 source 및 초기 properties 가 캐시됩니다. 로더가 active 로 만들어지면 source 컴포넌트의 인스턴스가 초기 properties 설정으로 생성됩니다.

이러한 방식으로 컴포넌트 인스턴스의 초기 속성 값을 설정해도 연결된 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도 참조하세요 .


© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.