Place QML Type

Le type de lieu représente un emplacement qui est une position d'intérêt. Plus d'informations...

• Liste de tous les membres, y compris les membres hérités

Propriétés

• attribution : string
• categories : list<Category>
• contactDetails : ContactDetails
• detailsFetched : bool
• editorialModel : EditorialModel
• extendedAttributes : ExtendedAttributes
• favorite : Place
• icon : Icon
• imageModel : ImageModel
• location : QtPositioning::Location
• name : string
• placeId : string
• plugin : Plugin
• primaryEmail : string
• primaryFax : string
• primaryPhone : string
• primaryWebsite : string
• ratings : Ratings
• reviewModel : ReviewModel
• status : enumeration
• supplier : Supplier
• visibility : enumeration

Méthodes

• void copyFrom(Place original)
• string errorString()
• void getDetails()
• void initializeFavorite(Plugin destinationPlugin)
• void remove()
• void save()

Description détaillée

Le type Place représente un emplacement physique avec des métadonnées supplémentaires décrivant cet emplacement. Il s'oppose aux types Location, Address et coordonnées qui sont utilisés pour décrire l'emplacement d'un lieu. Les propriétés de base d'un lieu sont name et location.

Les objets Lieu sont généralement obtenus à partir d'un modèle de recherche et leurs propriétés de base sont généralement les seules à être définies. La propriété detailsFetched peut être utilisée pour tester si d'autres valeurs de propriété doivent être extraites du site Plugin. Pour ce faire, il suffit d'invoquer la méthode getDetails(). La progression de l'opération de récupération peut être surveillée à l'aide de la propriété status, qui prend la valeur Place.Fetching lorsque les détails sont récupérés.

Le type Place possède de nombreuses propriétés contenant des informations sur le lieu. Les détails sur la façon de contacter le lieu sont disponibles à partir de la propriété contactDetails. Des propriétés pratiques permettant d'obtenir les adresses primaires phone, fax, email et website sont également disponibles.

Chaque lieu se voit attribuer zéro ou plusieurs categories. Les catégories sont généralement utilisées pour rechercher un type de lieu particulier, tel qu'un restaurant ou un hôtel. Certains lieux ont un objet ratings, qui donne une indication de la qualité du lieu.

Les métadonnées des lieux sont fournies par un supplier qui peut exiger qu'un message attribution soit affiché à l'intention de l'utilisateur lorsque les détails du lieu sont consultés.

Les lieux ont un icon associé qui peut être utilisé pour représenter un lieu sur une carte ou pour décorer un délégué dans une vue.

Les lieux peuvent être associés à un contenu riche supplémentaire. Les contenus riches actuellement pris en charge comprennent les descriptions éditoriales, les critiques et les images. Ils sont exposés sous la forme d'un ensemble de modèles permettant de récupérer le contenu. Les descriptions éditoriales du lieu sont disponibles à partir de la propriété editorialModel. Les critiques du lieu sont disponibles à partir de la propriété reviewModel. Une galerie d'images du lieu est accessible à partir de la propriété imageModel.

Les lieux peuvent avoir des attributs supplémentaires qui ne sont pas couverts par l'API officielle. La propriété extendedAttributes permet d'y accéder. Le type d'attributs étendus disponibles est spécifique à chaque site Plugin.

Un lieu est presque toujours lié à un plugin. La propriété plugin doit être définie avant qu'il ne soit possible d'appeler save(), remove() ou getDetails(). Les propriétés reviewModel, imageModel et editorialModel ne sont valables que si la propriété plugin est activée.

Sauvegarde d'un lieu

Si le site Plugin le permet, le type Place peut être utilisé pour enregistrer un lieu. Créez d'abord un nouveau lieu et définissez ses propriétés :

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
}

Ensuite, invoquez la méthode save() :

    myPlace.save();

La propriété status deviendra Place.Saving, puis Place.Ready si la sauvegarde a réussi ou Place.Error si une erreur s'est produite.

Si la propriété placeId est définie, le backend mettra à jour un lieu existant, sinon il créera un nouveau lieu. En cas de succès, la propriété placeId sera mise à jour avec l'identifiant du nouveau lieu sauvegardé.

Mise en garde

L'API Places est actuellement conçue pour enregistrer uniquement les détails de core. L'enregistrement d'un contenu riche tel que des images et des commentaires ou de détails tels que le fournisseur et la note n'est pas un cas d'utilisation pris en charge. En règle générale, un gestionnaire ignore ces champs lors de l'enregistrement et peut produire un message d'avertissement s'ils sont renseignés.

L'API Lieux ne prend en charge que l'enregistrement des informations de base suivantes :

• nom
• identifiant du lieu
• lieu
• coordonnées du contact
• icône
• catégories (noms semblables à des tags pour décrire un lieu)
• champ de visibilité

Il est possible que les fournisseurs ne prennent en charge qu'un sous-ensemble de ces éléments. Voir la documentation du plugin pour plus de détails.

L'enregistrement de propriétés telles que le classement, les attributs étendus, les images, les critiques, les éditoriaux et les fournisseurs n'est explicitement pas pris en charge par l'API Lieux.

Sauvegarde entre plugins

Lors de la sauvegarde de lieux entre plugins, il y a quelques points à prendre en compte. Certains champs d'un lieu, tels que l'identifiant, les catégories et les icônes, sont des entités spécifiques à un plugin. Par exemple, les catégories d'un gestionnaire peuvent ne pas être reconnues dans un autre. Il n'est donc pas possible d'essayer de sauvegarder un lieu directement d'un plugin à l'autre.

Il est généralement recommandé que la sauvegarde entre plugins soit gérée comme la sauvegarde de favorites, comme expliqué dans la section Favoris. Cependant, il existe une autre approche qui consiste à créer un nouveau lieu, à définir son plugin (de destination), puis à utiliser la méthode copyFrom() pour copier les détails du lieu d'origine. L'utilisation de copyFrom() ne copie que les données prises en charge par le plugin de destination ; les données spécifiques au plugin, telles que l'identifiant du lieu, ne sont pas copiées. Une fois la copie effectuée, le lieu est dans un état approprié pour être sauvegardé.

L'extrait suivant fournit un exemple de sauvegarde d'un lieu dans un plugin différent à l'aide de la méthode copyFrom:

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

Suppression d'un lieu

Pour supprimer un lieu, assurez-vous qu'il existe un objet Place avec une propriété placeId valide et appelez sa méthode remove(). La propriété status passera à Place.Removing puis à Place.Ready si la sauvegarde a réussi ou à Place.Error en cas d'erreur.

Favoris

L'API Places prend en charge le concept de favoris. Les favoris sont généralement mis en œuvre à l'aide de deux plugins. Le premier plugin est généralement une source de lieux en lecture seule (plugin d'origine) et un second plugin en lecture/écriture (plugin de destination) est utilisé pour stocker les lieux de l'origine en tant que favoris.

Chaque lieu possède une propriété favorite destinée à contenir le lieu correspondant du plugin de destination (le lieu lui-même provient du plugin d'origine). Comme les instances du lieu d'origine et du favori sont toutes deux disponibles, le développeur peut choisir les propriétés à montrer à l'utilisateur. Par exemple, le favori peut avoir un nom modifié qui doit être affiché plutôt que le nom original.

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

L'exemple suivant montre comment enregistrer une nouvelle instance de favori. Un appel est fait pour créer/initialiser l'instance de favori, puis l'instance est sauvegardée.

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

L'exemple suivant illustre la suppression d'un favori :

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;

Le site PlaceSearchModel possède une propriété favoritesPlugin. Si cette propriété est définie, tous les lieux trouvés au cours d'une recherche sont comparés au favoritesPlugin pour voir s'il existe un lieu favori correspondant. Si c'est le cas, la propriété favorite du lieu est définie, sinon la propriété favorite reste nulle.

Voir également PlaceSearchModel.

Documentation sur les propriétés

attribution : string

Cette propriété contient une chaîne d'attribution en texte enrichi pour le lieu. Certains fournisseurs peuvent exiger que l'attribution soit montrée à l'utilisateur chaque fois qu'un lieu est affiché. Le contenu de cette propriété doit être affiché à l'utilisateur s'il n'est pas vide.

categories : list<Category> [read-only]

Cette propriété contient la liste des catégories dont ce lieu est membre. Les catégories qui peuvent être attribuées à un lieu sont spécifiques à chaque plugin.

contactDetails : ContactDetails [read-only]

Cette propriété contient les informations de contact pour ce lieu, par exemple un numéro de téléphone ou l'URL d'un site web. Cette propriété est une carte des objets contactDetail.

detailsFetched : bool [read-only]

Cette propriété indique si les détails du lieu ont été récupérés. Si cette propriété vaut false, les détails du lieu n'ont pas encore été récupérés. La recherche peut être effectuée en invoquant la méthode getDetails().

Voir aussi getDetails().

editorialModel : EditorialModel [read-only]

Cette propriété contient un modèle qui peut être utilisé pour récupérer les descriptions éditoriales du lieu.

extendedAttributes : ExtendedAttributes [read-only]

Cette propriété contient les attributs étendus d'un lieu. Les attributs étendus sont des informations supplémentaires sur un lieu qui ne sont pas couvertes par les propriétés du lieu.

favorite : Place

Cette propriété contient l'instance favorite d'un lieu.

icon : Icon

Cette propriété contient une icône graphique qui peut être utilisée pour représenter le lieu.

imageModel : ImageModel [read-only]

Cette propriété contient un modèle qui peut être utilisé pour récupérer des images du lieu.

location : QtPositioning::Location

Cette propriété contient l'emplacement du lieu qui peut être utilisé pour récupérer les coordonnées, l'adresse et le cadre de délimitation.

name : string

Cette propriété contient le nom du lieu qui peut être utilisé pour représenter le lieu.

placeId : string

Cette propriété contient l'identifiant unique du lieu. L'identifiant du lieu n'a de sens que pour le site Plugin qui l'a généré et n'est pas transférable entre les sites Plugins. Il n'est pas garanti que l'identifiant du lieu soit universellement unique, mais il est unique pour le site Plugin qui l'a généré.

Si seul l'identifiant du lieu est connu, toutes les autres données relatives au lieu peuvent être extraites du site Plugin.

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

plugin : Plugin

Cette propriété contient le site Plugin qui a fourni ce lieu et qui peut être utilisé pour obtenir plus d'informations sur le service.

primaryEmail : string [read-only]

Cette propriété contient l'adresse électronique principale du lieu. Si aucun contact "email" n'est défini pour ce lieu, cette propriété sera une chaîne vide. Elle est équivalente à

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

primaryFax : string [read-only]

Cette propriété contient le numéro de fax principal du lieu. Si aucun contact "fax" n'est défini pour ce lieu, cette propriété sera une chaîne vide. Elle est équivalente à

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

primaryPhone : string [read-only]

Cette propriété contient le numéro de téléphone principal du lieu. Si aucune coordonnée "téléphone" n'est définie pour ce lieu, cette propriété sera une chaîne vide. Elle est équivalente à :

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

primaryWebsite : string [read-only]

Cette propriété contient l'url du site web principal du lieu. Si aucune information de contact "site web" n'est définie pour ce lieu, cette propriété sera une chaîne vide. Elle est équivalente à

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

ratings : Ratings

Cette propriété contient les évaluations du lieu. Les évaluations donnent une indication de la qualité d'un lieu.

reviewModel : ReviewModel [read-only]

Cette propriété contient un modèle qui peut être utilisé pour récupérer des avis sur le lieu.

status : enumeration [read-only]

Cette propriété détient le statut du lieu. Il peut s'agir de l'un des éléments suivants

L'état d'un lieu peut être vérifié en connectant la propriété status à une fonction de traitement, et en demandant à la fonction de traitement de traiter le changement d'état.

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

Cette propriété indique le fournisseur des données sur le lieu. Le fournisseur est généralement une entreprise ou une organisation qui a collecté les données sur le lieu.

visibility : enumeration

Cette propriété contient la visibilité du lieu. Elle peut être l'une des suivantes :

Notez que la visibilité n'affecte pas la façon dont le lieu est affiché dans l'interface utilisateur d'une application sur l'appareil. Elle définit plutôt la sémantique de partage du lieu.

Documentation de la méthode

void copyFrom(Place original)

Copie les données d'un lieu original dans ce lieu. Seules les données prises en charge par le plugin de ce lieu sont copiées et les données spécifiques au plugin, telles que l'identifiant du lieu, ne sont pas copiées.

string errorString()

Renvoie une chaîne de caractères décrivant l'erreur de la dernière opération. Si la dernière opération s'est déroulée avec succès, la chaîne est vide.

void getDetails()

Cette méthode permet de commencer à récupérer les détails d'un lieu.

La propriété status sera remplacée par Place.Fetching pendant que la recherche est en cours. En cas de succès, les propriétés de l'objet sont mises à jour, status devient Place.Ready et detailsFetched devient true. En cas d'erreur, status sera défini comme Place.Error. La méthode errorString() peut être utilisée pour obtenir les détails de l'erreur.

void initializeFavorite(Plugin destinationPlugin)

Crée une instance de favori pour le lieu qui doit être enregistré dans le plugin de destination destinationPlugin. Cette méthode ne fait rien si la propriété favorite n'est pas null.

void remove()

Cette méthode permet d'effectuer une opération de suppression sur le lieu.

La propriété status devient Place.Removing pendant que l'opération de sauvegarde est en cours. En cas de succès, status sera défini comme Place.Ready. En cas d'erreur, status devient Place.Error. La méthode errorString() peut être utilisée pour obtenir les détails de l'erreur.

void save()

Cette méthode effectue une opération de sauvegarde sur le lieu.

La propriété status devient Place.Saving pendant que l'opération de sauvegarde est en cours. En cas de succès, la propriété status sera définie comme Place.Ready. En cas d'erreur, status prend la valeur Place.Error. La méthode errorString() peut être utilisée pour obtenir les détails de l'erreur.

Si la propriété placeId était auparavant vide, une valeur valide lui sera automatiquement attribuée lors d'une opération d'enregistrement réussie.

Il convient de noter qu'un site PlaceSearchModel appellera Place::getDetails à tout endroit où il détecte une mise à jour. Il en résulte que chaque fois qu'un lieu d'un PlaceSearchModel est sauvegardé avec succès, il est suivi d'une récupération des détails du lieu, ce qui entraîne une séquence de changements d'état : Saving, Ready, Fetching, Ready.