Place QML Type

Le type « Lieu » désigne un emplacement présentant un intérêt particulier. En savoir plus…

• 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 lieu physique accompagné de métadonnées supplémentaires décrivant ce lieu. Il se distingue des types « Location », « Address » et « geoCoordinate », qui sont utilisés pour décrire l’emplacement d’un lieu. Les propriétés de base d’une « Place » sont ses coordonnées ( name ) et sa distance ( location).

Les objets « Place » sont généralement obtenus à partir d’un modèle de recherche et ne disposent, en règle générale, que de leurs propriétés de base. La propriété « detailsFetched » permet de vérifier si d’autres valeurs de propriétés doivent être récupérées à partir du « Plugin ». Pour ce faire, il suffit d’appeler 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 prendra la valeur Place.Fetching lorsque les détails sont en cours de récupération.

Le type Place dispose de nombreuses propriétés contenant des informations sur le lieu. Les détails permettant de contacter le lieu sont disponibles via la propriété contactDetails. Des propriétés pratiques permettant d’obtenir l’ phone principal, fax, email et website sont également disponibles.

À chaque lieu sont attribuées zéro ou plusieurs categories. Les catégories sont généralement utilisées lors de la recherche d’un type particulier de lieu, tel qu’un restaurant ou un hôtel. Certains lieux disposent d’un objet ratings, qui donne une indication sur la qualité du lieu.

Les métadonnées d’un lieu sont fournies par un « supplier » qui peut exiger qu’un message « attribution » soit affiché à l’utilisateur lors de la consultation des détails du lieu.

Les lieux sont associés à un icon qui peut être utilisé pour représenter un lieu sur une carte ou pour agrémenter un délégué dans une vue.

Les lieux peuvent être associés à du contenu enrichi supplémentaire. Le contenu enrichi actuellement pris en charge comprend des descriptions rédactionnelles, des avis et des images. Ceux-ci sont exposés sous la forme d’un ensemble de modèles permettant de récupérer le contenu. Les descriptions rédactionnelles du lieu sont disponibles via la propriété editorialModel. Les avis sur le lieu sont disponibles via la propriété reviewModel. Une galerie de photos du lieu est accessible via la propriété imageModel.

Les lieux peuvent présenter 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 Plugin.

Un lieu est presque toujours lié à une plugin. La propriété plugin doit être définie avant de pouvoir appeler save(), remove() ou getDetails(). Les méthodes reviewModel, imageModel et editorialModel ne sont valides que si la propriété plugin est définie.

Enregistrer un lieu

Si l’ Plugin le prend en charge, le type Place peut être utilisé pour enregistrer un lieu. Commencez par créer un nouvel objet Place 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
}

Appelez ensuite la méthode save():

    myPlace.save();

La propriété ` status ` prendra la valeur `Place.Saving`, puis `Place.Ready` si l'enregistrement a réussi, ou `Place.Error` en cas d'erreur.

Si la propriété ` placeId ` est définie, le backend mettra à jour un lieu existant ; dans le cas contraire, il en créera un nouveau. En cas de réussite, la propriété ` placeId ` sera mise à jour avec l’identifiant du lieu nouvellement enregistré.

Avertissements

L’API Places est actuellement conçue pour enregistrer uniquement les détails de l’ core. L’enregistrement de contenus enrichis tels que des images et des avis, ou de détails tels que le fournisseur et la note, n’est pas pris en charge. En règle générale, un gestionnaire ignorera ces champs lors de l’enregistrement et pourra afficher un message d’avertissement s’ils sont renseignés.

L’API Places ne prend en charge l’enregistrement que des informations essentielles suivantes :

• nom
• ID du lieu
• emplacement
• coordonnées
• icône
• catégories (noms de type « balises » pour décrire un lieu)
• champ d'application de la visibilité

Il est possible que certains fournisseurs ne prennent en charge qu’une partie de ces éléments. Consultez la documentation du plugin pour plus de détails.

L'enregistrement de propriétés telles que la note, les attributs étendus, les images, les avis, les articles rédactionnels et le fournisseur n'est explicitement pas pris en charge par l'API Places.

Enregistrement entre plugins

Lors de l'enregistrement de lieux entre plugins, il convient de tenir compte de certains éléments. Certains champs d'un lieu, tels que l'identifiant, les catégories et les icônes, sont des entités spécifiques à chaque plugin. Par exemple, les catégories d'un gestionnaire peuvent ne pas être reconnues par un autre. Il n'est donc pas possible d'enregistrer un lieu directement d'un plugin à un autre.

Il est généralement recommandé de traiter l’enregistrement entre plugins comme un enregistrement d’ favorites, comme expliqué dans la section « Favoris ». Il existe toutefois une autre approche consistant à 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 prêt à être enregistré.

L'extrait de code suivant fournit un exemple d'enregistrement d'un lieu dans un autre plugin à 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’un objet Place disposant d’une propriété placeId valide existe, puis appelez sa méthode remove(). La propriété status passera à Place.Removing, puis à Place.Ready si l’enregistrement 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 est généralement une source de lieux en lecture seule (plugin d’origine), tandis qu’un second plugin en lecture/écriture (plugin de destination) est utilisé pour enregistrer les lieux provenant de la source d’origine en tant que favoris.

Chaque instance Place dispose d’une propriété « favorite » destinée à contenir le lieu correspondant provenant 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 à afficher à l’utilisateur. Par exemple, le favori peut avoir un nom modifié qui doit être affiché à la place du nom d’origine.

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

L’exemple suivant montre comment enregistrer une nouvelle instance de favori. Un appel est effectué pour créer/initialiser l’instance de favori, puis celle-ci est enregistré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;

L’objet ` PlaceSearchModel ` dispose d’une propriété `favoritesPlugin`. Si cette propriété est définie, tous les lieux trouvés lors d’une recherche sont comparés au `favoritesPlugin` afin de vérifier s’il existe un lieu favori correspondant. Si c’est le cas, la propriété `favorite` du `Place` est définie ; sinon, elle reste nulle.

Voir également PlaceSearchModel.

Documentation sur les propriétés

attribution : string

Cette propriété contient une chaîne de texte enrichie indiquant les mentions légales relatives au lieu. Certains fournisseurs peuvent exiger que ces mentions légales soient affichées à 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 auxquelles appartient ce lieu. Les catégories pouvant être attribuées à un lieu sont propres à chaque plugin.

contactDetails : ContactDetails [read-only]

Cette propriété contient les coordonnées de ce lieu, par exemple un numéro de téléphone ou l'URL d'un site web. Cette propriété est une collection d'objets de type « 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é prend la valeur « false », cela signifie que les détails du lieu n'ont pas encore été récupérés. La récupération peut être effectuée en appelant la méthode getDetails().

Voir également getDetails().

editorialModel : EditorialModel [read-only]

Cette propriété contient un modèle permettant de récupérer les descriptions rédactionnelles du lieu.

extendedAttributes : ExtendedAttributes [read-only]

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

favorite : Place

Cette propriété contient l'instance préférée d'un lieu.

icon : Icon

Cette propriété contient une icône graphique pouvant servir à représenter le lieu.

imageModel : ImageModel [read-only]

Cette propriété contient un modèle permettant de 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 désigner ce dernier.

placeId : string

Cette propriété contient l'identifiant unique du lieu. L'identifiant du lieu n'a de sens que pour l'Plugin qui l'a généré et n'est pas transférable entre les Plugins. L'identifiant du lieu n'est pas garanti d'être universellement unique, mais il est unique au sein de l'Plugin qui l'a généré.

Si seul l’identifiant du lieu est connu, toutes les autres données relatives à ce lieu peuvent être récupérées auprès de l’ Plugin.

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

plugin : Plugin

Cette propriété contient l'Plugin, qui a fourni cette entité et qui peut être utilisée pour obtenir davantage d'informations sur le service.

primaryEmail : string [read-only]

Cette propriété contient l'adresse e-mail principale du lieu. Si aucune coordonnée de type « e-mail » n'est définie pour ce lieu, cette propriété sera une chaîne vide. Elle équivaut à

    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 aucune coordonnée « fax » n'est définie pour ce lieu, cette propriété sera une chaîne vide. Elle équivaut à

    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 de type « téléphone » n'est définie pour ce lieu, cette propriété sera une chaîne vide. Cela équivaut à :

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

primaryWebsite : string [read-only]

Cette propriété contient l'URL principale du site web du lieu. Si aucune coordonnée de type « site web » n'est définie pour ce lieu, cette propriété sera une chaîne vide. Elle équivaut à

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

ratings : Ratings

Cette rubrique présente les notes attribuées à cet établissement. Ces notes donnent une idée de la qualité de l'établissement.

reviewModel : ReviewModel [read-only]

Cette propriété contient un modèle permettant de récupérer les avis concernant ce lieu.

status : enumeration [read-only]

Cette propriété indique le statut du lieu. Elle peut prendre l'une des valeurs suivantes :

Il est possible de vérifier l'état d'un lieu en associant la propriété « status » à une fonction de gestion, puis en laissant cette dernière 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 relatives au lieu. Il s'agit généralement d'une entreprise ou d'une organisation qui a collecté les données concernant ce lieu.

visibility : enumeration

Cette propriété indique la visibilité du lieu. Elle peut prendre l’une des valeurs suivantes :

Notez que la visibilité n'affecte pas la manière dont le lieu est affiché dans l'interface utilisateur d'une application sur l'appareil. Elle définit plutôt les règles de partage du lieu.

Documentation des méthodes

void copyFrom(Place original)

Copie les données d'un emplacement « original » vers cet emplacement. Seules les données prises en charge par le plugin de cet emplacement sont copiées ; les données spécifiques au plugin, telles que l'identifiant de l'emplacement, ne sont pas copiées.

string errorString()

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

void getDetails()

Cette méthode lance la récupération des détails du lieu.

La propriété « status » prendra la valeur « Place.Fetching » tant que la récupération est en cours. En cas de réussite, les propriétés de l'objet seront mises à jour, la propriété « status » sera définie sur « Place.Ready » et la propriété « detailsFetched » sera définie sur « true ». En cas d'erreur, la propriété « status » sera définie sur « Place.Error ». La méthode « errorString() » permet d'obtenir les détails de l'erreur.

void initializeFavorite(Plugin destinationPlugin)

Crée une instance « favorite » pour l'emplacement qui doit être enregistré dans le plugin de destination destinationPlugin. Cette méthode ne fait rien si la propriété « favorite » n'est pas définie ( null).

void remove()

Cette méthode effectue une opération de suppression sur l'élément « place ».

La propriété status prendra la valeur Place.Removing pendant que l'opération d'enregistrement est en cours. En cas de réussite, status sera défini sur Place.Ready. En cas d'erreur, status sera défini sur Place.Error. La méthode errorString() permet d'obtenir les détails de l'erreur.

void save()

Cette méthode effectue une opération d'enregistrement sur le lieu.

La propriété « status » prendra la valeur « Place.Saving » pendant que l'opération d'enregistrement est en cours. En cas de réussite, la propriété « status » sera définie sur « Place.Ready ». En cas d'erreur, la propriété « status » sera définie sur « 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.

Notez qu’un « PlaceSearchModel » appellera la méthode « Place::getDetails » pour chaque lieu sur lequel il détecte une mise à jour. Il en résulte que chaque fois qu’un lieu issu d’un « PlaceSearchModel » est enregistré avec succès, cette opération est suivie 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 ».