QML API мест

Обзор

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

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

Плагин

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

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

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

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

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

В разделе «Общие примеры использования» ниже показаны конкретные примеры того, как эти концепции работают вместе.

Общие примеры использования

Поиск мест

Поиск выполняется с помощью 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() соответственно. Обратите внимание, что для сохранения Place должен быть назначен Plugin, чтобы указать, в какой бэкенд сохранять. Свойство 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 мест. См. раздел «Типы мест» ниже для более подробной информации о таких элементах, как изображения, отзывы и т. д., а также более подробные описания и пояснения.

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

Типы мест

Типы данных

Модели