QML-Places-API

Übersicht

Mit der Orte-API können Nutzer interessante Orte entdecken und Details dazu anzeigen, wie beispielsweise Adressen und Kontaktinformationen. Zu einigen Orten können zusätzliche Inhalte wie Bilder und Bewertungen gehören. Mit der Orte-API können Sie außerdem Orte und Kategorien verwalten und diese speichern oder entfernen. Orte können auch Wege, Straßen oder Verkehrsmittel umfassen, was eine Optimierung und Unterstützung der Navigation ermöglicht. Weitere Informationen zur Navigation finden Sie unter routes.

Einführende Konzepte

Plugin

Ein „ Plugin “ ist eine Abstraktion für ein Backend. Ein „ Plugin “ kann beispielsweise auf Orte über einen REST-Server zugreifen, während ein anderes auf Orte aus einer lokalen Datenbank zugreift. Im folgenden Beispiel wird ein „ Plugin “-Objekt instanziiert, indem der Name „osm“ angegeben wird. Der Name „ Plugin “ legt fest, welches Backend verwendet werden soll. Plugins können auch mit einer Reihe von „ parameters “ bereitgestellt werden, die im Wesentlichen die Form einer Reihe von Schlüssel-Wert-Paaren annehmen. Die „ parameters “, die angegeben werden können, variieren je nach den verschiedenen „ Plugin “-Backends. Dokumentation zu den möglichen „ parameters “ und den Nuancen der einzelnen „ Plugin “ finden Sie in den Plugin-Referenzen.

Plugin {
    id: myPlugin
    name: "osm"
    //specify plugin parameters as necessary
    //PluginParameter {...}
    //PluginParameter {...}
    //...
}

Modelle, Ansichten und Delegaten

Die QML Places API basiert auf dem Konzept von Modellen, Ansichten und Delegaten.

Der Abschnitt „Häufige Anwendungsfälle“ weiter unten zeigt konkrete Beispiele dafür, wie diese Konzepte zusammenwirken.

Häufige Anwendungsfälle

Suche nach Orten

Die Suche erfolgt über die Schnittstelle „ PlaceSearchModel “. Die Eigenschaft „ plugin “ legt fest, in welchem Backend Suchvorgänge durchgeführt werden sollen. Suchparameter können über Eigenschaften wie „ searchTerm “ und „ searchArea “ bereitgestellt werden. Ein Suchvorgang kann dann durch Aufruf der Methode „ update()“ gestartet werden. Der Einfachheit halber ruft der folgende Codeausschnitt „ update()“ auf, sobald die Erstellung des Modells abgeschlossen ist; in der Regel würde „ update()“ jedoch als Reaktion auf eine Benutzeraktion wie einen Klick auf eine Schaltfläche aufgerufen werden. Während der Suchvorgang läuft, wechselt die Eigenschaft „ PlaceSearchModel::status “ in den Zustand „ Loading “ und geht nach erfolgreichem Abschluss in den Zustand „ Ready “ über.

PlaceSearchModel {
    id: searchModel

    plugin: myPlugin

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

    Component.onCompleted: update()

}

Anzeige der Suchergebnisse mithilfe einer ListView

Eine „ ListView “ kann verwendet werden, um die vom Modell gefundenen Suchergebnisse anzuzeigen. Sie definiert den visuellen Bereich, in dem die Ergebnisse angezeigt werden, und füllt im folgenden Beispiel den gesamten Bereich ihres übergeordneten Elements aus. Die „ ListView “ verfügt über ein integriertes Verhalten, das es dem Bereich ermöglicht, auf Wischgesten zu reagieren und entsprechend zu scrollen.

Im folgenden Codeausschnitt wurde das Suchmodell der Eigenschaft „ model “ der „ ListView “ zugewiesen. Wenn das Modell mit neuen Ergebnissen aktualisiert wird, wird die „ ListView “ automatisch aktualisiert, um die neuen Datenelemente des Modells widerzuspiegeln.

Ein einfacher Delegat wurde an die Eigenschaft „ delegate “ des „ ListView “ gebunden. Der „ PlaceSearchModel “ stellt eine Reihe von „ roles “ bereit, von denen im folgenden Beispiel die Rollen „title“ und „place“ verwendet wurden; diese sind vom Typ „string“ bzw. „ Place “. Im Wesentlichen ruft die Ansicht für jedes Datenelement, das in der Ansicht sichtbar sein soll, den Delegaten auf, um eine visuelle Darstellung des Elements zu erstellen.

ListView { anchors.fill: parent model: searchModel delegate: Component { Row { spacing: 5 Marker { height: parent.height } Column { Text { text: title; font.bold: true } Text { text: place.location.address.text } } } } }

Den vollständigen Quellcode finden Sie im Beispiel „Places List “.

Anzeige von Suchergebnissen mit einer „MapItemView“

Anstelle eines „ ListView “ kann das „ PlaceSearchModel “ in Verbindung mit einem „ MapItemView “ verwendet werden, um Marker auf einer Karte anzuzeigen. Zunächst wird ein „ Map “ verwendet, um den visuellen Bereich zu definieren, den die Karte einnimmt; in diesem Fall füllt sie den gesamten Bereich ihres übergeordneten Elements aus. Weitere Eigenschaften werden festgelegt, wie beispielsweise die „ plugin “, die die Karten bereitstellt, sowie die „ center “ und „ zoomLevel “ der Karte.

Innerhalb des „ Map “ wird ein „ MapItemView “ deklariert, bei dem die Eigenschaft „ model “ auf das Suchmodell gesetzt wurde und ein „ delegate “, bestehend aus einem „ MapQuickItem “, zur Anzeige eines Markerbildes verwendet wird. Für jeden Ort, der vom Suchmodell gefunden wurde, wird ein Marker angezeigt. Der Delegat nutzt die Rolle „place“, um den Marker zu positionieren.

MapView { id: view anchors.fill: parent map.plugin: myPlugin; map.center: positionSource.lastSearchPosition map.zoomLevel: 13 MapItemView { model: searchModel parent: view.map delegate: MapQuickItem { coordinate: place.location.coordinate anchorPoint.x: image.width * 0.5 anchorPoint.y: image.height sourceItem: Column { Image { id: image; source: "marker.png" } Text { text: title; font.bold: true } } } } }

Den vollständigen Quellcode finden Sie im Beispiel „Places Map “.

Abrufen von Ortsdetails

Um Bandbreite zu sparen, gibt ein Backend manchmal nur Orte zurück, deren Details nur teilweise ausgefüllt sind. Dies lässt sich mit der Eigenschaft „ Place::detailsFetched “ überprüfen, die angibt, ob alle verfügbaren Details abgerufen wurden oder nicht. Ist dies nicht der Fall, kann die Methode „ Place::getDetails()“ aufgerufen werden, um die restlichen Details abzurufen.

if (!place.detailsFetched)
    place.getDetails();

Speichern und Löschen von Orten

Einige Backends unterstützen möglicherweise das Speichern und Löschen von Orten. Dies kann durch den Aufruf der Methoden „ Place::save()“ bzw. „ Place::remove()“ erfolgen. Beachten Sie, dass zum Speichern eines „ Place “ ein „ Plugin “ zugewiesen werden muss, um anzugeben, in welchem Backend gespeichert werden soll. Die Eigenschaft „ status “ wechselt während des Speichervorgangs in den Status „ Saving “ und geht nach erfolgreichem Abschluss in den Status „ Ready “ über. Der folgende Codeausschnitt zeigt, wie ein Ort mithilfe von JavaScript gespeichert und entfernt wird.

//creating and saving a place
var place = Qt.createQmlObject('import QtLocation; Place { }', parent);
place.plugin = myPlugin;
place.name = "New York";
place.location.coordinate.latitude = 40.7
place.location.coordinate.longitude = -74.0
place.save();

//removing a place
place.remove();

Weitere Informationen

Die obigen Codeausschnitte zeigen nur einen kleinen Ausschnitt der „Places“-Funktionalität. Weitere Informationen zu umfangreicheren Inhalten wie „ images “, „ reviews “ usw. sowie ausführlichere Beschreibungen und Erläuterungen finden Sie in den unten aufgeführten „Places“-Typen.

Siehe auch das Beispiel „Places (QML) “ für eine umfassendere Demonstration der Verwendung der API.

Ortsarten

Datentypen

Modelle