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 предоставляет набор ролей placesearchmodel-roles, из которых роли 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.

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

Отображение результатов поиска с помощью 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 } } } } }

Примечание: для простоты мы предположили, что каждый результат поиска имеет тип type 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.

Типы мест

Типы данных

Модели