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

Установка значения в неактивное состояние приведет к освобождению любого загруженного элементом 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 будут кэшированы. Когда загрузчик станет активным, будет создан экземпляр компонента source с установленными начальными properties.

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

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

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