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

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

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

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

Типы мест

Типы данных

Модели