Тип QML Loader

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

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

Свойства

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

Сигналы

• loaded()

Методы

• object setSource(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, загруженный Loader, но не повлияет на 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(источник, объект свойства)

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

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

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

Обратите внимание, что кэшированные свойства будут очищены, если свойство источник или 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.
    }
}

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