PlaceSearchModel QML Type

Permet d'accéder aux résultats de recherche par lieu. En savoir plus...

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

Propriétés

• categories : list<Category>
• count : int
• favoritesMatchParameters : VariantMap
• favoritesPlugin : Plugin
• incremental : bool (since QtLocation 5.12)
• limit : int
• nextPagesAvailable : bool
• plugin : Plugin
• previousPagesAvailable : bool
• recommendationId : string
• relevanceHint : enumeration
• searchArea : variant
• searchTerm : string
• status : enum
• visibilityScope : enum

Signaux

• dataChanged()

Méthodes

• void cancel()
• Variant data(int index, string role)
• string errorString()
• void nextPage()
• void previousPage()
• void reset()
• void update()
• void updateWith(int proposedSearchIndex)

Description détaillée

PlaceSearchModel fournit un modèle de résultats de recherche de lieux au sein de l'searchArea. Les propriétés searchTerm et categories peuvent être définies pour limiter les résultats de recherche aux lieux correspondant à ces critères.

PlaceSearchModel renvoie à la fois des résultats de recherche sponsorisés et naturels. Les résultats de recherche sponsorisés auront le rôle « sponsored » défini sur « true ».

Le modèle renvoie des données pour les rôles suivants :

Types de résultats de recherche

Le rôle « type » peut prendre les valeurs suivantes :

Il est souvent utile d'utiliser une interface « Loader » pour créer un délégué qui choisira différentes méthodes « Component» en fonction du type de résultat de recherche.

Component {
    id: resultDelegate
    Loader {
        Component {
            id: placeResult

            Column {
                Text { text: title }
                Text { text: place.location.address.text }
            }
        }

        Component {
            id: otherResult
            Text { text: title }
        }

        sourceComponent: type == PlaceSearchModel.PlaceResult ? placeResult :
                                                                otherResult
    }
}

Détection des lieux mis à jour et supprimés

Le `PlaceSearchModel` surveille les lieux qui ont été mis à jour ou supprimés du backend de son plugin. S’il détecte qu’un lieu a été mis à jour et que ce lieu est actuellement présent dans le modèle, il appelle alors ` Place::getDetails ` pour actualiser les détails. S'il détecte qu'un lieu a été supprimé, celui-ci sera alors supprimé du modèle s'il y figure actuellement.

Exemple

L'exemple suivant montre comment utiliser le PlaceSearchModel pour rechercher des pizzerias à proximité immédiate d'une position donnée. Une requête de recherche ( searchTerm ) et une requête de mise à jour ( searchArea ) sont fournies au modèle, et la méthode update() est utilisée pour effectuer une requête de recherche. Notez que le modèle ne récupère pas les résultats de recherche de manière incrémentielle, mais effectue une seule récupération lorsque la méthode update() est exécutée. La variable ` count ` est définie sur le nombre de résultats de recherche renvoyés lors de cette récupération.

import QtQuick
import QtPositioning
import QtLocation

PlaceSearchModel {
    id: searchModel

    plugin: myPlugin

    searchTerm: "food"
    searchArea: QtPositioning.circle(startCoordinate, 5000 /* 5 km radius */);

    Component.onCompleted: update()

}

Pagination

L'API PlaceSearchModel offre une prise en charge limitée de la pagination. Les fonctions nextPage() et previousPage(), ainsi que la propriété limit, peuvent être utilisées pour accéder aux résultats de recherche paginés. Lorsque la propriété limit est définie, la page de résultats de recherche contient au maximum limit entrées (de type « place result »). Par exemple, si le backend contient au total 5 résultats de recherche [a, b, c, d, e], et en supposant que la première page soit affichée et que la limite soit fixée à 3, alors a, b, c sont renvoyés. La méthode nextPage() renverrait d, e. Les propriétés nextPagesAvailable et previousPagesAvailable peuvent être utilisées pour vérifier s’il existe d’autres pages. Pour l’instant, l’API ne prend pas en charge les moyens permettant de récupérer le nombre total d’éléments disponibles dans le backend. Notez que la prise en charge de nextPage(), previousPage() et limit peut varier en fonction de la plugin.

Voir également CategoryModel et QPlaceManager.

Documentation sur les propriétés

categories : list<Category> [read-only]

Cette propriété contient une liste de catégories à utiliser lors d'une recherche. Les résultats de recherche renvoyés concerneront les lieux correspondant à au moins l'une de ces catégories.

count : int [read-only]

Cette propriété indique le nombre de résultats fournis par le modèle.

Notez qu'elle ne fait pas référence au nombre total de résultats de recherche disponibles dans le backend. Le nombre total de résultats de recherche n'est actuellement pas pris en charge par l'API.

favoritesMatchParameters : VariantMap

Cette propriété contient un ensemble de paramètres permettant de définir la manière dont les résultats de recherche sont mis en correspondance avec les favoris dans l'favoritesPlugin.

Par défaut, la table de correspondance des paramètres est vide, ce qui signifie que le plugin « Favoris » effectue la mise en correspondance à l’aide d’identifiants alternatifs. En règle générale, un développeur d’application n’aura pas besoin de définir cette propriété.

Dans les cas où le plugin « Favoris » ne prend pas en charge la mise en correspondance via des identifiants alternatifs, il convient de consulter la documentation du plugin pour savoir précisément quels paramètres clé-valeur définir.

favoritesPlugin : Plugin

Cette propriété contient la valeur « Plugin », qui sera utilisée pour rechercher les favoris. Pour tous les lieux issus de la recherche pouvant faire l'objet d'un recoupement ou d'une correspondance dans le « favoritesPlugin », la propriété « favorite » sera définie sur la valeur « Place » correspondante issue du « favoritesPlugin ».

Si le plugin « favoritesPlugin » n’est pas défini, la propriété « favorite » des lieux figurant dans les résultats sera toujours nulle.

Voir également Favorites.

incremental : bool [since QtLocation 5.12]

Cette propriété détermine l’impact de la pagination sur l’ PlaceSearchModel. Si la valeur est « true », l’appel de ` previousPage ` ou ` nextPage ` ne réinitialisera pas le modèle ; les nouveaux résultats seront plutôt ajoutés à la fin du modèle. La valeur par défaut est « false ».

Cette propriété a été introduite dans QtLocation 5.12.

limit : int

Cette propriété définit la limite du nombre d'éléments qui seront renvoyés.

nextPagesAvailable : bool [read-only]

Cette propriété s'applique qu'il y ait une ou plusieurs pages supplémentaires de résultats de recherche disponibles.

Voir également nextPage().

plugin : Plugin

Cette propriété contient l'Plugin, qui sera utilisé pour effectuer la recherche.

previousPagesAvailable : bool [read-only]

Cette propriété s'applique qu'il y ait une ou plusieurs pages précédentes de résultats de recherche disponibles.

Voir également previousPage().

recommendationId : string

Cette propriété contient l'identifiant « placeId » qui sert à trouver des recommandations de lieux similaires.

relevanceHint : enumeration

Cette propriété contient une indication de pertinence utilisée dans la requête de recherche. Cette indication est fournie au fournisseur afin de l'aider à établir le classement des résultats, sans toutefois le dicter. Par exemple, l'indication de distance peut attribuer un meilleur classement aux lieux les plus proches, mais cela ne signifie pas nécessairement que les résultats seront classés strictement en fonction de la distance. Un fournisseur peut choisir d'ignorer complètement cette indication.

searchArea : variant

Cette propriété définit la zone de recherche. Les résultats de recherche renvoyés par le modèle se situeront dans cette zone.

Si cette propriété est définie sur un objet de type « geoCircle », sa propriété « radius » peut être laissée vide ; dans ce cas, le moteur de recherche « Plugin » choisira un rayon approprié pour la recherche.

La prise en charge de la spécification d’une zone de recherche peut varier en fonction de l’implémentation du backend d’ plugin. Par exemple, certains peuvent ne prendre en charge qu’un centre de recherche, tandis que d’autres peuvent uniquement prendre en charge des rectangles géographiques.

searchTerm : string

Cette propriété contient le terme de recherche utilisé dans la requête. Le terme de recherche est une chaîne de texte au format libre.

status : enum [read-only]

Cette propriété indique l'état du modèle. Elle peut prendre l'une des valeurs suivantes :

visibilityScope : enum

Cette propriété définit la portée de visibilité des lieux à rechercher. Seuls les lieux présentant la visibilité spécifiée apparaîtront dans les résultats de recherche.

La portée de visibilité peut être l'une des suivantes :

Documentation Signal

dataChanged()

Ce signal est émis lorsque des modifications importantes ont été apportées au magasin de données sous-jacent.

Les applications doivent réagir à ce signal à leur entière discrétion. Les données fournies par le modèle peuvent être obsolètes et celui-ci doit donc être mis à jour à un moment donné ; toutefois, une mise à jour immédiate peut déconcerter les utilisateurs si les résultats changent sans qu'ils n'aient rien fait.

Le gestionnaire correspondant est onDataChanged.

Documentation de la méthode

void cancel()

Annule immédiatement une opération de recherche en cours et définit l'état du modèle sur « PlaceSearchModel.Ready ». Le modèle conserve tous les résultats de recherche dont il disposait avant le lancement de l'opération.

Si aucune opération n'est en cours, l'appel de la fonction `cancel()` n'a aucun effet.

Voir également update() et status.

Variant data(int index, string role)

Renvoie les données d'une « role » donnée à l'index de ligne spécifiée.

string errorString()

Cette propriété en lecture seule contient la description textuelle de la dernière erreur du modèle de recherche de lieux. Si aucune erreur ne s'est produite ou si le modèle a été effacé, une chaîne vide est renvoyée.

Une chaîne vide peut également être renvoyée si une erreur s'est produite qui ne dispose d'aucune représentation textuelle associée.

void nextPage()

Actualise le modèle pour afficher la page suivante des résultats de recherche. S'il n'y a pas de page suivante, cette méthode ne fait rien.

void previousPage()

Actualise le modèle pour afficher la page précédente des résultats de recherche. S'il n'y a pas de page précédente, cette méthode ne fait rien.

void reset()

Réinitialise le modèle. Tous les résultats de recherche sont effacés, les requêtes en cours sont annulées et les éventuelles erreurs sont corrigées. L'état du modèle sera défini sur « PlaceSearchModel.Null ».

void update()

Met à jour le modèle en fonction des paramètres de requête fournis. Le modèle sera renseigné avec une liste de lieux correspondant aux paramètres de recherche spécifiés par les propriétés du type. Les critères de recherche sont définis en configurant des propriétés telles que « searchTerm », « categories », « searchArea » et « limit ». La prise en charge de ces propriétés peut varier en fonction de plugin. update() soumet ensuite l’ensemble des critères à plugin pour traitement.

Pendant la mise à jour du modèle, la propriété status du modèle est définie sur PlaceSearchModel.Loading. Si la mise à jour du modèle réussit, la propriété status est définie sur PlaceSearchModel.Ready, tandis que si elle échoue, la propriété status est définie sur PlaceSearchModel.Error et le modèle est effacé.

PlaceSearchModel {
    id: model
    plugin: backendPlugin
    searchArea: QtPositioning.circle(QtPositioning.coordinate(10, 10))
    ...
}

MouseArea {
    ...
    onClicked: {
        model.searchTerm = "pizza";
        model.categories = null;  //not searching by any category
        model.searchArea.center.latitude = -27.5;
        model.searchArea.center.longitude = 153;
        model.update();
    }
}

Voir également cancel() et status.

void updateWith(int proposedSearchIndex)

Met à jour le modèle en fonction du `ProposedSearchResult` à l'index ` proposedSearchIndex`. Le modèle sera renseigné avec une liste de lieux correspondant à la recherche proposée. L'état du modèle sera défini sur ` PlaceSearchModel`.Loading. Si la mise à jour du modèle s'effectue correctement, l'état sera défini sur ` PlaceSearchModel`.Ready. En cas d'erreur, l'état sera défini sur ` PlaceSearchModel`.Error et le modèle sera vidé.

Si ` proposedSearchIndex ` ne fait pas référence à un `ProposedSearchResult`, cette méthode ne fait rien.