PlaceSearchModel QML Type

Permet d'accéder aux résultats de la recherche de lieux. Plus d'informations...

• 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 dans le site searchArea. Les propriétés searchTerm et categories peuvent être définies pour restreindre les résultats de la recherche aux lieux correspondant à ces critères.

Le modèle PlaceSearchModel renvoie des résultats de recherche sponsorisés et organiques. Pour les résultats de recherche sponsorisés, le rôle sponsored est 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 peut souvent être utile d'utiliser Loader pour créer un délégué qui choisira différents Componenten fonction du type de résultat de la 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 modèle PlaceSearchModel est à l'écoute des 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 appellera Place::getDetails pour rafraîchir les détails. S'il détecte qu'un lieu a été supprimé, le lieu sera supprimé du modèle s'il est actuellement présent.

Exemple

L'exemple suivant montre comment utiliser le modèle PlaceSearchModel pour rechercher des restaurants de pizzas à proximité d'une position donnée. Les adresses searchTerm et searchArea sont fournies au modèle et update() est utilisé pour effectuer une recherche. Notez que le modèle ne récupère pas les résultats de la recherche de manière incrémentale, mais qu'il effectue une seule récupération lorsque update() est exécuté. La valeur de count correspond au nombre de résultats de recherche renvoyés lors de la recherche.

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 la recherche contient au maximum limit entrées (de type place result). Par exemple, si le backend a 5 résultats de recherche au total [a,b,c,d,e], et en supposant que la première page est affichée et que la limite de 3 a été fixée, a,b,c est renvoyé. L'adresse nextPage() renverrait d,e. Les propriétés nextPagesAvailable et previousPagesAvailable peuvent être utilisées pour vérifier la présence d'autres pages. Pour l'instant, l'API ne permet pas de récupérer le nombre total d'éléments disponibles dans le dossier. Notez que la prise en charge des propriétés nextPage(), previousPage() et limit peut varier en fonction de la propriété 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 de la recherche. Les résultats de recherche renvoyés concernent les lieux qui correspondent à au moins une des catégories.

count : int [read-only]

Cette propriété indique le nombre de résultats du 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 utilisés pour spécifier la manière dont les lieux de résultats de recherche sont associés aux favoris dans le site favoritesPlugin.

Par défaut, la carte des paramètres est vide et implique que le plugin des favoris correspond à des identifiants alternatifs. En général, le développeur d'une application n'aura pas besoin de définir cette propriété.

Dans les cas où le plugin de favoris ne prend pas en charge la correspondance par identifiants alternatifs, il convient de consulter la documentation du plugin pour connaître précisément les paramètres clé-valeur à définir.

favoritesPlugin : Plugin

Cette propriété contient l'adresse Plugin qui sera utilisée pour rechercher des favoris. Tous les lieux de la recherche qui peuvent faire l'objet d'une référence croisée ou d'une correspondance dans le favoriPlugin verront leur propriété favorite remplacée par la propriété Place correspondante du favoriPlugin.

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

Voir aussi Favorites.

incremental : bool [since QtLocation 5.12]

Cette propriété contrôle l'effet de la pagination sur PlaceSearchModel. Si elle est vraie, l'appel à previousPage ou nextPage ne réinitialisera pas le modèle, mais les nouveaux résultats seront ajoutés au modèle. La valeur par défaut est false.

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

limit : int

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

nextPagesAvailable : bool [read-only]

Cette propriété indique si une ou plusieurs pages supplémentaires de résultats de recherche sont disponibles.

Voir également nextPage().

plugin : Plugin

Cette propriété contient le site Plugin qui sera utilisé pour effectuer la recherche.

previousPagesAvailable : bool [read-only]

Cette propriété indique si une ou plusieurs pages précédentes de résultats de recherche sont disponibles.

Voir également previousPage().

recommendationId : string

Cette propriété contient l'identifiant du lieu à utiliser pour trouver des recommandations pour des lieux similaires.

relevanceHint : enumeration

Cette propriété contient un indice de pertinence utilisé dans la requête de recherche. L'indice est donné au fournisseur pour l'aider à classer les résultats, mais ne lui impose pas de le faire. Par exemple, l'indice de distance peut donner un meilleur classement aux lieux les plus proches, mais cela ne signifie pas nécessairement que les résultats seront strictement classés en fonction de la distance. Un fournisseur peut ignorer complètement l'indice.

searchArea : variant

Cette propriété définit la zone de recherche. Le résultat de la recherche renvoyé par le modèle se situe à l'intérieur de la zone de recherche.

Si cette propriété est attribuée à geoCircle, sa propriété radius peut être laissée non définie, auquel cas 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 la mise en œuvre du backend plugin. Par exemple, certains peuvent ne prendre en charge qu'un centre de recherche, tandis que d'autres ne prennent en charge que les 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 libre.

status : enum [read-only]

Cette propriété contient le statut du modèle. Elle peut être l'une des suivantes

visibilityScope : enum

Cette propriété contient l'étendue de la visibilité des lieux à rechercher. Seuls les lieux ayant la visibilité spécifiée seront affichés dans les résultats de la recherche.

L'étendue de la visibilité peut être l'une des suivantes

Documentation sur le signal

dataChanged()

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

Les applications doivent agir en fonction de ce signal à leur propre discrétion. Les données fournies par le modèle peuvent être obsolètes et le modèle doit donc être réactualisé à un moment donné. Toutefois, une réactualisation immédiate peut déconcerter les utilisateurs si les résultats changent sans qu'ils aient eu à intervenir.

Le gestionnaire correspondant est onDataChanged.

Documentation de la méthode

void cancel()

Annule immédiatement une opération de recherche en cours et règle l'état du modèle sur PlaceSearchModel.Ready. Le modèle conserve tous les résultats de recherche qu'il avait avant le début de l'opération.

Si une opération n'est pas en cours, l'invocation de cancel() n'a aucun effet.

Voir également update() et status.

Variant data(int index, string role)

Renvoie les données pour un role donné à la ligne spécifiée index.

string errorString()

Cette propriété en lecture seule contient la présentation 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 sans représentation textuelle associée.

void nextPage()

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

void previousPage()

Met à jour le modèle pour afficher la page précédente des résultats de la 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 la recherche sont effacés, les demandes en cours sont abandonnées et les erreurs éventuelles sont effacées. L'état du modèle prend la valeur PlaceSearchModel.Null.

void update()

Met à jour le modèle sur la base des paramètres de requête fournis. Le modèle sera alimenté par 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 spécifiés en définissant 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 que le modèle est mis à jour, la valeur status du modèle est fixée à PlaceSearchModel.Loading. Si le modèle est mis à jour avec succès, la valeur status est fixée à PlaceSearchModel.Ready, tandis que si la mise à jour échoue, la valeur status est fixée à 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 sur la base du résultat de la recherche proposée à l'adresse proposedSearchIndex. Le modèle sera alimenté par une liste de lieux correspondant à la recherche proposée. L'état du modèle devient PlaceSearchModel.Loading. Si la mise à jour du modèle est réussie, l'état devient PlaceSearchModel.Ready. En cas d'erreur, l'état devient PlaceSearchModel.Error et le modèle est effacé.

Si proposedSearchIndex ne fait pas référence à un résultat de recherche proposé, cette méthode ne fait rien.