Тип 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("Loaded item 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 не станет активным.

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

Статус неактивного Loader всегда Null.

См. также source и sourceComponent.

asynchronous : bool

Это свойство содержит информацию о том, будет ли компонент создан асинхронно.

При использовании совместно со свойством source, загрузка и компиляция также будут выполняться в фоновом потоке.

Асинхронная загрузка создаёт объекты, объявленные компонентом в течение нескольких кадров, и уменьшает вероятность появления артефактов в анимации. При асинхронной загрузке статус изменится на Loader.Loading. После создания всего компонента элемент item станет доступным, и статус изменится на Loader.Ready.

Чтобы избежать постепенной загрузки элементов, установите 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.