Тип QML Place

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

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

Свойства

• attribution : строка
• categories : список<Category>
• contactDetails : ContactDetails
• detailsFetched : bool
• 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(original)
• строка errorString()
• void getDetails()
• void initializeFavorite(destinationPlugin)
• void remove()
• void save()

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

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

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

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

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

Сохранение таких свойств, как рейтинг, расширенные атрибуты, изображения, отзывы, статьи и поставщик, не поддерживается 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 : string

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

categories : list<Category>

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

contactDetails : ContactDetails

Это свойство содержит контактную информацию для этого места, например, номер телефона или адрес веб-сайта. Это свойство представляет собой карту объектов 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(original)

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

string errorString()

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

void getDetails()

Этот метод запускает процесс получения подробностей о месте.

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

void initializeFavorite(destinationPlugin)

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