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, предоставляющий карты, а также центр 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 } } } } }

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

См. пример «Карта мест» для полного исходного кода.

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

Для экономии пропускной способности иногда бэкэнд возвращает места, частично заполненные подробностями. Это можно проверить с помощью свойства 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();

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

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

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

Типы мест

Типы данных

Модели