API мест QML

Обзор

API мест позволяет пользователям находить интересные места и просматривать подробную информацию о них, такую как адрес и контактные данные. Некоторые места могут иметь дополнительное содержимое, такое как изображения и отзывы. API мест также облегчает управление местами и категориями, позволяя пользователям сохранять и удалять их.

Вводные понятия

Плагин

Плагин — это абстракция для бэкенда. Один плагин может получать доступ к местам с REST-сервера, а другой — из локальной базы данных. Следующий фрагмент кода создает объект плагина, указав имя «osm». Имя плагина определяет, какой бэкенд выбрать. Плагины также могут получать набор параметров, которые по сути представляют собой набор пар ключ-значение. Параметры, которые можно указать, различаются в зависимости от различных бэкендов плагинов. Документация по возможным параметрам и особенностям каждого плагина доступна в разделе «Справочные материалы и параметры плагинов».

Plugin {
    id: myPlugin
    name: "osm"
    //specify plugin parameters as necessary
    //PluginParameter {...}
    //PluginParameter {...}
    //...
}

Примечание: Плагину HERE необходимо предоставить некоторые обязательные параметры, как указано в документации по плагину HERE.

Модели, представления и делегаты

API мест QML построен на концепции моделей, представлений и делегатов.

В разделе «Примеры типичных случаев использования» ниже приведены конкретные примеры того, как эти понятия объединяются.

Примеры типичных случаев использования

Поиск мест

Поиск выполняется с помощью модели PlaceSearchModel. Свойство plugin указывает, какой бэкенд использовать для выполнения операций поиска. Параметры поиска могут быть заданы с помощью свойств, таких как searchTerm и searchArea. Операцию поиска можно запустить, вызвав метод update(). Для простоты в приведенном фрагменте кода метод update() вызывается после создания модели, обычно update() вызывается в ответ на действие пользователя, например, нажатие кнопки. Пока операция поиска выполняется, свойство PlaceSearchModel::status переходит в состояние Loading и при успешном завершении переходит в состояние Ready.

PlaceSearchModel {
    id: searchModel

    plugin: myPlugin

    searchTerm: "pizza"
    searchArea: QtPositioning.circle(startCoordinate);

    Component.onCompleted: update()

}

Отображение результатов поиска с помощью ListView

ListView можно использовать для отображения результатов поиска, найденных моделью. Он определяет визуальную область, где отображаются результаты, и в данном случае заполняет весь родительский элемент. ListView имеет встроенное поведение, которое позволяет области реагировать на прокрутку и соответствующим образом прокручивать.

В приведенном фрагменте кода модель поиска назначена свойству model ListView. Когда модель обновляется новыми результатами, ListView автоматически обновляется, чтобы отразить новые элементы данных модели.

Простой делегат связан со свойством delegate ListView. PlaceSearchModel предоставляет набор ролей, среди которых роли title и place использованы ниже; они имеют тип string и Place соответственно. По сути, для каждого элемента данных, который должен быть виден в представлении, представление вызывает делегат для создания визуального представления элемента.

ListView { anchors.fill: parent model: searchModel delegate: Component { Row { spacing: 5 Marker { height: parent.height } Column { Text { text: title; font.bold: true } Text { text: place.location.address.text } } } } }

Примечание: Для простоты мы предполагаем, что каждый результат поиска имеет тип PlaceSearchResult и поэтому всегда имеет доступ к роли place; другие типы результатов поиска могут не иметь роли place.

Полный исходный код см. в примере «Список мест».

Отображение результатов поиска с помощью MapItemView

Вместо ListView модель PlaceSearchModel может использоваться совместно с MapItemView для отображения маркеров на карте. Во-первых, используется Map для определения визуальной области, занимаемой картой; в данном случае она заполняет весь родительский элемент. Указываются другие свойства, такие как свойство plugin, предоставляющее карты, а также центр и масштаб карты.

Внутри Map объявляется MapItemView, где свойство model установлено на модель поиска, а делегат, состоящий из MapQuickItem, используется для отображения изображения маркера. Маркер отображается для каждого места, найденного моделью поиска. Делегат использует роль place для позиционирования маркера.

Map { id: map anchors.fill: parent plugin: myPlugin; center: locationOslo zoomLevel: 13 MapItemView { model: searchModel delegate: MapQuickItem { coordinate: place.location.coordinate anchorPoint.x: image.width * 0.5 anchorPoint.y: image.height sourceItem: Column { Image { id: image; source: "marker.png" } Text { text: title; font.bold: true } } } } }

Примечание: Для простоты мы предполагаем, что каждый результат поиска имеет тип PlaceSearchResult и поэтому всегда имеет доступ к роли place; другие типы результатов поиска могут не иметь роли place.

Полный исходный код см. в примере «Карта мест».

Получение подробной информации о месте

Для экономии пропускной способности бэкенд иногда возвращает места, частично заполненные деталями. Это можно проверить с помощью свойства Place::detailsFetched, которое указывает, были ли получены все доступные детали или нет. Если нет, можно вызвать метод Place::getDetails() для получения оставшихся деталей.

if (!place.detailsFetched)
    place.getDetails();

Сохранение и удаление мест

Некоторые бэкенды могут поддерживать сохранение и удаление мест. Это можно сделать, вызвав методы Place::save и Place::remove соответственно. Обратите внимание, что для сохранения места плагин должен быть назначен, чтобы указать, в какой бэкенд мы сохраняем. Свойство status перейдет в состояние Saving во время операции сохранения и при успешном завершении перейдет в состояние Ready. Следующий фрагмент кода демонстрирует, как сохранить и удалить место с помощью JavaScript.

//creating and saving a place
var place = Qt.createQmlObject('import QtLocation 5.3; Place { }', parent);
place.plugin = myPlugin;
place.name = "New York";
place.location.coordinate.latitude = 40.7
place.location.coordinate.longitude = -74.0
place.save();

//removing a place
place.remove();

Дополнительная информация

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

См. также пример «Места (QML)» для более подробной демонстрации использования API.

Типы мест

Типы данных

Модели