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 } } } } }

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

Полный исходный код см. в примере Places List.

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

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

Внутри 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 } } } } }

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

Полный исходный код см. в примере Places Map.

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

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

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

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

Некоторые бэкенды могут поддерживать сохранение и удаление мест. Это можно сделать, вызвав методы Place::save() и Place::remove() соответственно. Обратите внимание, что для сохранения Place должен быть назначен плагин, чтобы указать, в какой бэкенд сохранять. Свойство 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();

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

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

См. также пример Places (QML) для более подробного ознакомления с использованием API.

Типы мест

Типы данных

Модели