PlaceSearchModel QML Type

Bietet Zugriff auf die Suchergebnisse nach Orten. Mehr...

• Liste aller Elemente, einschließlich vererbter Elemente

Eigenschaften

• 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

Signale

• dataChanged()

Methoden

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

Ausführliche Beschreibung

PlaceSearchModel stellt ein Modell für die Ergebnisse der Ortssuche innerhalb der „ searchArea “ bereit. Die Eigenschaften „ searchTerm “ und „ categories “ können festgelegt werden, um die Suchergebnisse auf Orte zu beschränken, die diesen Kriterien entsprechen.

Das „PlaceSearchModel“ gibt sowohl gesponserte als auch organische Suchergebnisse zurück. Bei gesponserten Suchergebnissen ist die Rolle „ sponsored “ auf „true“ gesetzt.

Das Modell gibt Daten für die folgenden Rollen zurück:

Suchergebnistypen

Die Rolle „ type “ kann folgende Werte annehmen:

Oft ist es hilfreich, mithilfe von „ Loader “ einen Delegaten zu erstellen, der je nach Art des Suchergebnisses verschiedene „ Components“ auswählt.

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
    }
}

Erkennung aktualisierter und entfernter Orte

Das „PlaceSearchModel“ überwacht, ob Orte aktualisiert oder aus dem Backend seines Plugins entfernt wurden. Wenn es feststellt, dass ein Ort aktualisiert wurde und dieser Ort derzeit im Modell vorhanden ist, ruft es „ Place::getDetails “ auf, um die Details zu aktualisieren. Stellt es fest, dass ein Ort entfernt wurde, wird dieser entsprechend aus dem Modell entfernt, sofern er derzeit darin enthalten ist.

Beispiel

Das folgende Beispiel zeigt, wie man das PlaceSearchModel verwendet, um nach Pizzerien in unmittelbarer Nähe einer bestimmten Position zu suchen. Dem Modell werden eine ` searchTerm ` und eine ` searchArea ` bereitgestellt, und mit ` update()` wird eine Suchabfrage durchgeführt. Beachten Sie, dass das Modell die Suchergebnisse nicht schrittweise abruft, sondern einen einzigen Abruf durchführt, wenn ` update()` ausgeführt wird. Die Variable „ count “ wird auf die Anzahl der beim Abruf zurückgegebenen Suchergebnisse gesetzt.

import QtQuick
import QtPositioning
import QtLocation

PlaceSearchModel {
    id: searchModel

    plugin: myPlugin

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

    Component.onCompleted: update()

}

Paginierung

Die PlaceSearchModel-API bietet eine eingeschränkte Unterstützung für die Paginierung. Die Funktionen „ nextPage()“ und „ previousPage()“ sowie die Eigenschaft „ limit “ können verwendet werden, um auf paginierte Suchergebnisse zuzugreifen. Wenn die Eigenschaft „ limit “ festgelegt ist, enthält die Suchergebnisseite höchstens limit Einträge (vom Typ „place result“). Wenn das Backend beispielsweise insgesamt 5 Suchergebnisse [a, b, c, d, e] enthält und angenommen wird, dass die erste Seite angezeigt wird und ein Limit von 3 festgelegt wurde, werden a, b, c zurückgegeben. Die Methode ` nextPage()` würde `d` und `e` zurückgeben. Mit den Eigenschaften ` nextPagesAvailable ` und ` previousPagesAvailable ` kann nach weiteren Seiten gesucht werden. Derzeit bietet die API keine Möglichkeit, die Gesamtzahl der im Backend verfügbaren Elemente abzurufen. Beachten Sie, dass die Unterstützung für ` nextPage()`, ` previousPage()` und ` limit ` je nach plugin variieren kann.

Siehe auch CategoryModel und QPlaceManager.

Dokumentation zu den Eigenschaften

categories : list<Category> [read-only]

Diese Eigenschaft enthält eine Liste von Kategorien, die bei der Suche verwendet werden sollen. Die zurückgegebenen Suchergebnisse beziehen sich auf Orte, die mindestens einer der Kategorien entsprechen.

count : int [read-only]

Diese Eigenschaft gibt die Anzahl der Ergebnisse an, die das Modell liefert.

Beachten Sie, dass sich diese Angabe nicht auf die Gesamtzahl der im Backend verfügbaren Suchergebnisse bezieht. Die Gesamtzahl der Suchergebnisse wird derzeit von der API nicht unterstützt.

favoritesMatchParameters : VariantMap

Diese Eigenschaft enthält eine Reihe von Parametern, mit denen festgelegt wird, wie Suchergebnisse mit Favoriten in der „ favoritesPlugin “ abgeglichen werden.

Standardmäßig ist die Parameterzuordnung leer, was bedeutet, dass das Favoriten-Plugin anhand alternativer Identifikatoren abgleicht. In der Regel muss ein Anwendungsentwickler diese Eigenschaft nicht festlegen.

In Fällen, in denen das Favoriten-Plugin den Abgleich anhand alternativer Identifikatoren nicht unterstützt, sollte die Dokumentation des Plugins zu Rate gezogen werden, um genau zu erfahren, welche Schlüssel-Wert-Parameter gesetzt werden müssen.

favoritesPlugin : Plugin

Diese Eigenschaft enthält die „ Plugin “, die für die Suche nach Favoriten verwendet wird. Bei allen Orten aus der Suche, die im „favoritesPlugin“ abgeglichen oder zugeordnet werden können, wird die Eigenschaft „ favorite “ auf den entsprechenden „ Place “ aus dem „favoritesPlugin“ gesetzt.

Ist das „favoritesPlugin“ nicht festgelegt, ist die Eigenschaft „ favorite “ der Orte in den Ergebnissen immer null.

Siehe auch „ Favorites “.

incremental : bool [since QtLocation 5.12]

Diese Eigenschaft steuert, wie sich die Seitenaufteilung auf das „ PlaceSearchModel “ auswirkt. Ist der Wert „true“, wird das Modell durch den Aufruf von „ previousPage “ oder „ nextPage “ nicht zurückgesetzt, sondern es werden stattdessen neue Ergebnisse an das Modell angehängt. Der Standardwert ist „false“.

Diese Eigenschaft wurde in QtLocation 5.12 eingeführt.

limit : int

Diese Eigenschaft legt die Obergrenze für die Anzahl der zurückgegebenen Elemente fest.

nextPagesAvailable : bool [read-only]

Diese Eigenschaft gilt unabhängig davon, ob eine oder mehrere weitere Seiten mit Suchergebnissen verfügbar sind.

Siehe auch nextPage().

plugin : Plugin

Diese Eigenschaft enthält die „ Plugin “, die für die Durchführung der Suche verwendet wird.

previousPagesAvailable : bool [read-only]

Diese Eigenschaft gilt unabhängig davon, ob eine oder mehrere vorherige Seiten mit Suchergebnissen verfügbar sind.

Siehe auch previousPage().

recommendationId : string

Diese Eigenschaft enthält die „placeId“, die verwendet wird, um Empfehlungen für ähnliche Orte zu finden.

relevanceHint : enumeration

Diese Eigenschaft enthält einen Relevanzhinweis, der in der Suchanfrage verwendet wird. Der Hinweis wird dem Anbieter zur Verfügung gestellt, um die Rangfolge der Ergebnisse zu unterstützen, ohne sie jedoch vorzuschreiben. So kann beispielsweise der Entfernungshinweis näher gelegenen Orten eine höhere Rangfolge zuweisen, was jedoch nicht zwangsläufig bedeutet, dass die Ergebnisse streng nach der Entfernung sortiert werden. Ein Anbieter kann den Hinweis auch vollständig ignorieren.

searchArea : variant

Diese Eigenschaft gibt den Suchbereich an. Das vom Modell zurückgegebene Suchergebnis liegt innerhalb dieses Suchbereichs.

Wenn diese Eigenschaft auf eine „ geoCircle “ gesetzt ist, kann die Eigenschaft „ radius “ ungeachtet bleiben; in diesem Fall wählt das „ Plugin “ einen geeigneten Radius für die Suche aus.

Die Unterstützung für die Angabe eines Suchbereichs kann je nach der Backend-Implementierung von „ plugin “ variieren. Beispielsweise unterstützen einige nur einen Suchmittelpunkt, während andere möglicherweise nur Georechtecke unterstützen.

searchTerm : string

Diese Eigenschaft enthält den in der Abfrage verwendeten Suchbegriff. Der Suchbegriff ist eine frei formatierte Textzeichenfolge.

status : enum [read-only]

Diese Eigenschaft gibt den Status des Modells an. Mögliche Werte sind:

visibilityScope : enum

Diese Eigenschaft legt den Sichtbarkeitsbereich der zu durchsuchenden Orte fest. In den Suchergebnissen werden nur Orte mit der angegebenen Sichtbarkeit angezeigt.

Der Sichtbarkeitsbereich kann einer der folgenden sein:

Signal-Dokumentation

dataChanged()

Dieses Signal wird ausgegeben, wenn wesentliche Änderungen am zugrunde liegenden Datenspeicher vorgenommen wurden.

Anwendungen sollten nach eigenem Ermessen auf dieses Signal reagieren. Die vom Modell bereitgestellten Daten könnten veraltet sein, sodass das Modell irgendwann erneut aktualisiert werden sollte; eine sofortige Aktualisierung könnte jedoch für die Benutzer verwirrend sein, wenn sich die Ergebnisse ändern, ohne dass sie etwas dafür tun müssen.

Der entsprechende Handler lautet „ onDataChanged “.

Methodendokumentation

void cancel()

Bricht einen laufenden Suchvorgang sofort ab und setzt den Modellstatus auf „ PlaceSearchModel.Ready“. Das Modell behält alle Suchergebnisse bei, die vor Beginn des Vorgangs vorlagen.

Wenn kein Vorgang läuft, hat der Aufruf von `cancel()` keine Auswirkung.

Siehe auch „ update()“ und „ status “.

Variant data(int index, string role)

Gibt die Daten für eine bestimmte „ role “ an der angegebenen Zeilen index zurück.

string errorString()

Diese schreibgeschützte Eigenschaft enthält die textuelle Darstellung des letzten Fehlers des Ortssuchmodells. Wenn kein Fehler aufgetreten ist oder das Modell gelöscht wurde, wird eine leere Zeichenkette zurückgegeben.

Eine leere Zeichenkette kann auch zurückgegeben werden, wenn ein Fehler aufgetreten ist, für den keine zugehörige textuelle Darstellung vorhanden ist.

void nextPage()

Aktualisiert das Modell, um die nächste Seite der Suchergebnisse anzuzeigen. Wenn es keine nächste Seite gibt, führt diese Methode keine Aktion aus.

void previousPage()

Aktualisiert das Modell, um die vorherige Seite der Suchergebnisse anzuzeigen. Wenn es keine vorherige Seite gibt, führt diese Methode keine Aktion aus.

void reset()

Setzt das Modell zurück. Alle Suchergebnisse werden gelöscht, alle noch ausstehenden Anfragen werden abgebrochen und eventuelle Fehler werden behoben. Der Modellstatus wird auf „ PlaceSearchModel.Null“ gesetzt.

void update()

Aktualisiert das Modell auf Grundlage der angegebenen Abfrageparameter. Das Modell wird mit einer Liste von Orten gefüllt, die den in den Eigenschaften des Typs festgelegten Suchparametern entsprechen. Die Suchkriterien werden durch die Einstellung von Eigenschaften wie „ searchTerm “, „ categories “, „ searchArea “ und „ limit “ festgelegt. Die Unterstützung dieser Eigenschaften kann je nach plugin variieren. update() übermittelt anschließend die Kriterien an die plugin zur Verarbeitung.

Während das Modell aktualisiert wird, wird der Status „ status “ des Modells auf „ PlaceSearchModel.Loading “ gesetzt. Wird das Modell erfolgreich aktualisiert, wird der Status „ status “ auf „ PlaceSearchModel.Ready “ gesetzt; bei einem Fehlschlag wird der Status „ status “ auf „ PlaceSearchModel.Error “ gesetzt und das Modell gelöscht.

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();
    }
}

Siehe auch cancel() und status.

void updateWith(int proposedSearchIndex)

Aktualisiert das Modell auf Basis des „ProposedSearchResult“ unter dem Index „ proposedSearchIndex “. Das Modell wird mit einer Liste von Orten gefüllt, die der vorgeschlagenen Suche entsprechen. Der Status des Modells wird auf „ PlaceSearchModel.Loading“ gesetzt. Bei erfolgreicher Aktualisierung des Modells wird der Status auf „ PlaceSearchModel.Ready“ gesetzt. Tritt ein Fehler auf, wird der Status auf „ PlaceSearchModel.Error“ gesetzt und das Modell geleert.

Wenn „ proposedSearchIndex “ nicht auf ein „ProposedSearchResult“ verweist, führt diese Methode keine Aktion aus.