Тип 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 являются его имя и местоположение.

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

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

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

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

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

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

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

Объект Place почти всегда связан с 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 мест поддерживает сохранение только следующих основных деталей:

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

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

Сохранение свойств, таких как рейтинг, расширенные атрибуты, изображения, отзывы, редакционные материалы и поставщик, явно не поддерживается 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 остаётся null.

См. также PlaceSearchModel.

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

attribution : string

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

categories : list<Category>

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

contactDetails : ContactDetails

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

detailsFetched : bool

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

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

editorialModel : EditorialModel

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

extendedAttributes : ExtendedAttributes

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

favorite : Place

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

icon : Icon

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

imageModel : ImageModel

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

location : QtPositioning::Location

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

name : string

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

place : QPlace

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

placeId : string

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

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

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

plugin : Plugin

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

primaryEmail : string

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

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

primaryFax : string

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

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

primaryPhone : string

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

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

primaryWebsite : string

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

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

ratings : Ratings

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

reviewModel : ReviewModel

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

status : enumeration

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

Статус места можно проверить, подключив свойство 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 : enumeration

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

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

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

void copyFrom(Place original)

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

string errorString()

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

void getDetails()

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

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

void initializeFavorite(Plugin destinationPlugin)

Создаёт экземпляр избранного места, который будет сохранён в плагине destination. Этот метод ничего не делает, если свойство избранного места не равно 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.