Тип QML Loader

Позволяет динамически загружать поддерево из URL или компонента. Подробнее...

• Список всех членов, включая унаследованные члены

Свойства

• active : bool
• asynchronous : bool
• item : object
• progress : real
• source : url
• sourceComponent : Component
• status : перечисление

Сигналы

• loaded()

Методы

• object setSource(url source, object properties)

Подробное описание

Loader используется для динамической загрузки QML-компонентов.

Loader может загружать QML-файл (используя свойство source) или объект Component (используя свойство sourceComponent). Это полезно для отсрочки создания компонента до момента необходимости: например, когда компонент должен создаваться по требованию или когда компонент не должен создаваться излишне по соображениям производительности.

Вот пример Loader, который загружает "Page1.qml" как компонент при нажатии на MouseArea:

import QtQuick 2.0

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

Если компонент источника не является типом Item, Loader не применяет никаких специальных правил изменения размера. При использовании для загрузки визуальных типов, Loader применяет следующие правила изменения размера:

• Если для Loader не указан явный размер, Loader автоматически изменяет свой размер до размера загруженного элемента после загрузки компонента.
• Если размер Loader явно указан установкой ширины, высоты или привязки, загруженный элемент будет изменен до размера Loader.

В обоих случаях размеры элемента и Loader идентичны. Это гарантирует, что привязка к Loader эквивалентна привязке к загруженному элементу.

import QtQuick 2.0

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 2.0

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

Получение сигналов от загруженных объектов

Любые сигналы, исходящие от загруженного объекта, могут быть получены с помощью типа Connections. Например, следующий application.qml загружает MyItem.qml, и может получать сигнал message от загруженного элемента через объект Connections:

import QtQuick 2.0

Item {
    width: 100; height: 100

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

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

import QtQuick 2.0

Rectangle {
   id: myItem
   signal message(string msg)

   width: 100; height: 100

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

В качестве альтернативы, поскольку MyItem.qml загружен в пределах области действия Loader, он также может напрямую вызывать любую функцию, определенную в Loader или его родительском Item.

Фокус и события клавиатуры

Loader является областью фокуса. Его свойство focus должно быть установлено в true для любого из его дочерних элементов, чтобы получить активный фокус. (См. Фокус клавиатуры в Qt Quick для получения дополнительной информации.) Любые события клавиатуры, полученные в загруженном элементе, также должны быть приняты, чтобы они не передавались в Loader.

Например, следующий application.qml загружает KeyReader.qml при нажатии на MouseArea. Обратите внимание, что свойство focus установлено в true для Loader, а также для Item в динамически загруженном объекте:

import QtQuick 2.0

Rectangle {
    width: 200; height: 200

    Loader {
        id: loader
        focus: true
    }

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

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

import QtQuick 2.0

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

После того, как KeyReader.qml загружен, он принимает события клавиатуры и устанавливает event.accepted в true, чтобы событие не передавалось родительскому Rectangle.

Поскольку QtQuick 2.0, Loader также может загружать невизуальные компоненты.

Использование Loader в делегате просмотра

В некоторых случаях вам может потребоваться использовать Loader в делегате просмотра для повышения производительности загрузки делегата. Это хорошо работает в большинстве случаев, но есть одна важная проблема, связанная с контекстом создания создания компонента.

В следующем примере свойство контекста index , вставленное ListView в контекст delegateComponent будет недоступно для 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
            }
        }
    }
}

См. также Динамическое создание объектов.

Документация по свойствам

active : bool

Это свойство true если Loader в настоящее время активен. Значение по умолчанию для этого свойства равно true.

Если Loader неактивен, изменение source или sourceComponent не вызовет создание элемента до тех пор, пока Loader не станет активным.

Установка значения в неактивное состояние приведет к освобождению любого загруженного элементом item, но не повлияет на source или sourceComponent.

Состояние status неактивного Loader всегда равно 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 : object

Это свойство содержит верхний объект, который в данный момент загружен.

Поскольку QtQuick 2.0, Loader может загружать любые типы объектов.

progress : real

Это свойство содержит степень загрузки QML-данных из сети, от 0.0 (ничего не загружено) до 1.0 (завершено). Большинство QML-файлов довольно небольшие, поэтому это значение быстро изменится с 0 до 1.

См. также status.

source : url

Это свойство содержит URL QML-компонента для создания.

Поскольку 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 : перечисление

Это свойство содержит статус загрузки 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, или при успешной начальной загрузке.

Примечание: Соответствующий обработчик — onLoaded.

Документация по методам

object setSource(url source, object properties)

Создает экземпляр объекта заданного компонента source, который будет иметь заданные properties. Аргумент properties является необязательным. Экземпляр будет доступен через свойство item после завершения загрузки и инициализации.

Если свойство active равно false в момент вызова этой функции, заданный компонент source не будет загружен, но source и начальные properties будут кэшированы. При активации загрузчика (active) будет создан экземпляр компонента source с установленными начальными properties.

Установка начальных значений свойств экземпляра компонента таким образом не вызовет связанные с ним Behaviors.

Обратите внимание, что кэшированные properties будут очищены, если свойство source или sourceComponent будет изменено после вызова этой функции, но до установки свойства загрузчика active.

Пример:

// 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.