Тип 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 в делегате просмотра для повышения производительности загрузки делегата. Это работает хорошо в большинстве случаев, но есть одна важная проблема, связанная с контекстом создания Component.

В приведенном ниже примере свойство контекста 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 не станет активным.

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

Статус неактивного 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.

См. также источник и прогресс.

состояние : перечисление

Это свойство содержит состояние загрузки 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 всё равно будет вызван.

См. также прогресс.

Документация по сигналам

loaded()

Этот сигнал испускается, когда свойство состояние становится Loader.Ready, или при успешной начальной загрузке.

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

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

объект setSource(url источник, объект свойства)

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

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

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

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

Пример:

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

См. также источник и активный.