QML API Мест

Обзор

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, обеспечивающий карты, а также центр карты и zoomLevel.

Внутри Map объявляется MapItemView, где свойство model установлено в модель поиска, а delegate, состоящий из 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();

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

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

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

Типы мест

Типы данных

Модели