Тип QML Place

Тип Place представляет местоположение, которое является точкой интереса. Подробнее...

• Список всех членов, включая унаследованные

Свойства

• attribution : строка
• categories : список<Category>
• contactDetails : ContactDetails
• detailsFetched : булево
• editorialModel : EditorialModel
• extendedAttributes : ExtendedAttributes
• favorite : Place
• icon : Icon
• imageModel : ImageModel
• location : QtPositioning::Location
• name : строка
• place : QPlace
• placeId : строка
• plugin : Plugin
• primaryEmail : строка
• primaryFax : строка
• primaryPhone : строка
• primaryWebsite : строка
• ratings : Ratings
• reviewModel : ReviewModel
• status : перечисление
• supplier : Supplier
• visibility : перечисление

Методы

• void copyFrom(Place original)
• строка errorString()
• void getDetails()
• void initializeFavorite(Plugin destinationPlugin)
• void remove()
• void save()

Подробное описание

Тип Place представляет физическое местоположение с дополнительными метаданными, описывающими это местоположение. В отличие от типов Location, Address и coordinate, которые используются для описания местоположения. Основными свойствами места являются его имя и местоположение.

Объекты Place обычно получаются из модели поиска и обычно содержат только свои основные свойства. Свойство detailsFetched можно использовать для проверки необходимости получения дополнительных значений свойств из Plugin. Это можно сделать, вызвав метод getDetails(). Прогресс операции получения данных можно отслеживать с помощью свойства status, которое будет установлено в Place.Fetching, когда детали загружаются.

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

Каждому месту присвоено ноль или более категорий. Категории обычно используются при поиске определенного типа места, например, ресторана или отеля. У некоторых мест есть объект ratings, который дает представление о качестве места.

Метаданные места предоставляются поставщиком, который может потребовать отображения сообщения attribution пользователю при просмотре деталей места.

Места имеют связанный значок, который можно использовать для отображения места на карте или для украшения элемента в представлении.

Места могут иметь связанные с ними дополнительные богатые данные. В настоящее время поддерживаемые богатые данные включают редакционные описания, отзывы и изображения. Они представлены набором моделей для извлечения содержимого. Редакционные описания места доступны из свойства editorialModel. Отзывы о месте доступны из свойства reviewModel. Галерею изображений места можно получить, используя свойство imageModel.

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

Место почти всегда связано с plugin. Свойство plugin должно быть установлено, прежде чем можно будет вызвать save(), remove() или getDetails(). Свойства reviewModel, imageModel и editorialModel действительны только при установленном свойстве plugin.

Сохранение места

Если Plugin его поддерживает, тип Place может быть использован для сохранения места. Сначала создайте новый Place и установите его свойства:

Place {
    id: myPlace
    plugin: myPlugin

    name: "Brisbane Technology Park"
    location: Location {
        address: Address {
            street: "53 Brandl Street"
            city: "Eight Mile Plains"
            postalCode: "4113"
            country: "Australia"
        }
        coordinate {
            latitude: -27.579646
            longitude: 153.100308
        }
    }

    visibility: Place.PrivateVisibility
}

Затем вызовите метод save():

    myPlace.save();

Свойство status изменится на Place.Saving, а затем на Place.Ready, если сохранение прошло успешно, или на Place.Error, если произошла ошибка.

Если свойство placeId установлено, бэкэнд обновит существующее место, в противном случае создаст новое. В случае успеха свойство placeId будет обновлено с идентификатором сохранённого места.

Ограничения

API мест в настоящее время разработан только для сохранения основных деталей. Сохранение богатого содержимого, таких как изображения и отзывы, или деталей, таких как поставщик и рейтинг, не является поддерживаемым случаем использования. Обычно менеджер обычно игнорирует эти поля при сохранении и может вывести сообщение об ошибке, если они заполнены.

API мест поддерживает сохранение только следующих основных деталей:

• имя
• идентификатор места
• местоположение
• контактные данные
• значок
• категории (названия тегов для описания места)
• область видимости

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

Сохранение свойств, таких как рейтинг, расширенные атрибуты, изображения, отзывы, редакторские материалы и поставщик, явно не поддерживается API мест.

Сохранение между плагинами

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

Обычно рекомендуется, чтобы сохранение через плагины обрабатывалось как сохранение избранных мест, как описано в разделе «Избранное». Однако существует другой подход, который заключается в создании нового места, установке его (целевого) плагина и использовании метода copyFrom() для копирования деталей исходного места. С помощью copyFrom() копируются только данные, поддерживаемые целевым плагином, данные, специфичные для плагина, такие как идентификатор места, не копируются. После завершения копирования место находится в подходящем состоянии для сохранения.

Следующий фрагмент кода демонстрирует пример сохранения места в другом плагине с помощью метода copyFrom:

var place = Qt.createQmlObject('import QtLocation 5.3; Place { }', parent);
place.plugin = destinationPlugin;
place.copyFrom(originalPlace);
place.save();

Удаление места

Чтобы удалить место, убедитесь, что существует объект Place с действительным свойством placeId, и вызовите его метод remove(). Свойство status изменится на Place.Removing, а затем на Place.Ready, если сохранение прошло успешно, или на Place.Error, если произошла ошибка.

Избранные места

API мест поддерживает понятие избранных мест. Избранные места обычно реализуются с использованием двух плагинов: первый плагин — это, как правило, только для чтения источник мест (исходный плагин), а второй плагин для чтения/записи (целевой плагин) используется для хранения мест из исходного плагина как избранных.

У каждого места есть любимое свойство, которое должно содержать соответствующее место из плагина назначения (само место взято из плагина происхождения). Поскольку доступны как исходное место, так и экземпляр избранного, разработчик может выбрать, какие свойства отображать пользователю. Например, избранное может иметь изменённое имя, которое следует отображать вместо исходного имени.

Text { text: place.favorite ? place.favorite.name : place.name }

Следующее демонстрирует, как сохранить новый экземпляр избранного. Вызывается создание/инициализация экземпляра избранного, а затем экземпляр сохраняется.

place.initializeFavorite(destinationPlugin);
//if necessary customizations to the favorite can be made here.
//...
place.favorite.save();

Следующее демонстрирует удаление избранного:

place.favorite.remove();
    ...
//check successful removal of the favorite by monitoring its status.
//once that is done we can assign null to the favorite
place.favorite = null;

У PlaceSearchModel есть свойство favoritesPlugin. Если свойство установлено, все найденные места во время поиска проверяются на наличие соответствующего избранного места в favoritesPlugin. Если такое место есть, свойство favorite места устанавливается, в противном случае свойство favorite остаётся нулевым.

См. также PlaceSearchModel.

Документация по свойствам

attribution : строка

Это свойство содержит строку атрибуции места в формате rich text. Некоторые поставщики могут потребовать, чтобы атрибуция отображалась пользователю всякий раз, когда отображается место. Содержимое этого свойства должно отображаться пользователю, если оно не пусто.

categories : список<Category>

Это свойство содержит список категорий, к которым принадлежит это место. Категории, которые могут быть назначены месту, специфичны для каждого плагина.

contactDetails : ContactDetails

Это свойство содержит контактную информацию для этого места, например, номер телефона или адрес сайта. Это свойство является картой объектов ContactDetail.

detailsFetched : логическое

Это свойство указывает, были ли получены данные о месте. Если это свойство ложно, данные о месте ещё не получены. Получение данных можно осуществить, вызвав метод getDetails().

См. также getDetails().

editorialModel : EditorialModel

Это свойство содержит модель, которая может быть использована для получения редакторских описаний места.

extendedAttributes : ExtendedAttributes

Это свойство содержит расширенные атрибуты места. Расширенные атрибуты — это дополнительная информация о месте, не охваченная свойствами места.

favorite : Place

Это свойство содержит экземпляр избранного места.

icon : Icon

Это свойство содержит графический значок, который можно использовать для представления места.

imageModel : ImageModel

Это свойство содержит модель, которая может быть использована для получения изображений места.

location : QtPositioning::Location

Это свойство содержит местоположение места, которое можно использовать для получения координат, адреса и ограничивающей рамки.

name : строка

Это свойство содержит имя места, которое можно использовать для представления места.

place : QPlace

Подробнее о том, как использовать это свойство для взаимодействия между C++ и QML, см. "Взаимодействие между C++ и QML-кодом".

placeId : строка

Это свойство содержит уникальный идентификатор места. Идентификатор места имеет смысл только для плагина, который его сгенерировал, и не передаётся между плагинами. Идентификатор места не гарантируется как универсально уникальный, но уникален внутри плагина, который его сгенерировал.

Если известен только идентификатор места, все остальные данные о месте можно получить из плагина.

    place.plugin = myPlugin;
    place.placeId = "known-place-id";
    place.getDetails();

plugin : Plugin

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

primaryEmail : строка

Это свойство содержит основной адрес электронной почты места. Если для этого места не определён контактный detail "email", это свойство будет пустой строкой. Эквивалентно

    var primaryEmail;
    if (place.contactDetails["email"].length > 0)
        primaryEmail = place.contactDetails["email"][0].value;

primaryFax : строка

Это свойство содержит основной номер факса места. Если для этого места не определён контактный detail "fax", это свойство будет пустой строкой. Эквивалентно

    var primaryFax;
    if (place.contactDetails["fax"].length > 0)
        primaryFax = place.contactDetails["fax"][0].value;

primaryPhone : строка

Это свойство содержит основной номер телефона места. Если для этого места не определён контактный detail "phone", это свойство будет пустой строкой. Эквивалентно:

    var primaryPhone;
    if (place.contactDetails["phone"].length > 0)
        primaryPhone = place.contactDetails["phone"][0].value;

primaryWebsite : строка

Это свойство содержит основной адрес веб-сайта места. Если для этого места не определён контактный detail "website", это свойство будет пустой строкой. Эквивалентно

    var primaryWebsite;
    if (place.contactDetails["website"].length > 0)
        primaryWebsite = place.contactDetails["website"][0].value;

ratings : Ratings

Это свойство содержит оценки места. Рейтинги дают представление о качестве места.

reviewModel : ReviewModel

Это свойство содержит модель, которая может быть использована для получения отзывов о месте.

status : перечисление

Это свойство содержит статус места. Он может быть одним из:

Статус места можно проверить, связав свойство status с обработчиком функций, а затем позволить обработчику функций обработать изменение статуса.

place.statusChanged.connect(statusChangedHandler);
    ...
function statusChangedHandler() {
    if (statusChangedHandler.prevStatus === Place.Saving) {
        switch (place.status) {
        case Place.Ready:
            console.log('Save successful');
            break;
        case Place.Error:
            console.log('Save failed');
            break;
        default:
            break;
        }
    }
    statusChangedHandler.prevStatus = place.status;
}

supplier : Supplier

Это свойство содержит поставщика данных о месте. Поставщик, как правило, является предприятием или организацией, которая собрала данные о месте.

visibility : перечисление

Это свойство содержит видимость места. Оно может быть одним из:

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

Документация по методам

пусто copyFrom(Place original)

Копирует данные из места original в это место. Копируются только данные, поддерживаемые плагином этого места, а такие данные, как идентификатор места, специфичные для плагина, не копируются.

строка errorString()

Возвращает строку описания ошибки последней операции. Если последняя операция выполнена успешно, строка пустая.

пусто getDetails()

Этот метод начинает получение данных о месте.

Свойство status изменится на Place.Fetching во время извлечения. При успешном завершении свойства объекта будут обновлены, status будет установлено в Place.Ready, а detailsFetched — в true. При ошибке status будет установлено в Place.Error. Метод errorString() можно использовать для получения подробностей об ошибке.

void initializeFavorite(Plugin destinationPlugin)

Создает экземпляр избранного места, которое должно быть сохранено в плагине destination. Этот метод ничего не делает, если свойство favorite не равно null.

void remove()

Этот метод выполняет операцию удаления места.

Свойство status изменится на Place.Removing во время выполнения операции сохранения. В случае успеха свойство status будет установлено в Place.Ready. В случае ошибки свойство status будет установлено в Place.Error. Метод errorString() можно использовать для получения подробностей об ошибке.

void save()

Этот метод выполняет операцию сохранения места.

Свойство status изменится на Place.Saving во время выполнения операции сохранения. В случае успеха свойство status будет установлено в Place.Ready. В случае ошибки свойство status будет установлено в Place.Error. Метод errorString() можно использовать для получения подробностей об ошибке.

Если свойство placeId было ранее пустым, ему будет автоматически присвоено действительное значение во время успешной операции сохранения.

Обратите внимание, что PlaceSearchModel вызовет Place::getDetails для любого места, на котором он обнаруживает обновление. Следствием этого является то, что всякий раз, когда место из PlaceSearchModel успешно сохраняется, за этим последует получение подробностей о месте, что приведет к последовательности изменений состояния Saving, Ready, Fetching, Ready.