Тип 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
        function onMessage(msg) { 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: (event)=> {
        console.log("Captured:",
                    event.text);
    }
}

import QtQuick 2.0

Item {
    Item {
        focus: true
        Keys.onPressed: (event)=> {
            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, загруженного Loader, но не повлияет на 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.

Установка начальных значений свойств экземпляра компонента таким образом не вызовет какие-либо ассоциированные 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.