Place QML Type

Der Typ Ort stellt einen Ort dar, der eine Position von Interesse ist. Mehr...

• Liste aller Mitglieder, einschließlich geerbter Mitglieder

Eigenschaften

• 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

Methoden

• void copyFrom(Place original)
• string errorString()
• void getDetails()
• void initializeFavorite(Plugin destinationPlugin)
• void remove()
• void save()

Detaillierte Beschreibung

Der Typ Place stellt einen physischen Ort mit zusätzlichen Metadaten dar, die diesen Ort beschreiben. Im Gegensatz zu den Typen Location, Address und coordinate, die zur Beschreibung der Lage eines Ortes verwendet werden. Die grundlegenden Eigenschaften eines Ortes sind seine name und location.

Ortsobjekte werden in der Regel aus einem Suchmodell abgerufen und haben in der Regel nur ihre grundlegenden Eigenschaften eingestellt. Die Eigenschaft detailsFetched kann verwendet werden, um zu prüfen, ob weitere Eigenschaftswerte von Plugin abgerufen werden müssen. Dies kann durch den Aufruf der Methode getDetails() erfolgen. Der Fortschritt des Abrufvorgangs kann mit der Eigenschaft status überwacht werden, die auf Place.Fetching gesetzt wird, wenn die Details abgerufen werden.

Der Typ "Ort" hat viele Eigenschaften, die Informationen über den Ort enthalten. Einzelheiten darüber, wie der Ort kontaktiert werden kann, sind über die Eigenschaft contactDetails verfügbar. Es gibt auch praktische Eigenschaften zum Abrufen der primären phone, fax, email und website.

Jedem Ort sind null oder mehr categories zugeordnet. Kategorien werden in der Regel verwendet, wenn man nach einer bestimmten Art von Ort sucht, z. B. nach einem Restaurant oder Hotel. Einige Orte haben ein ratings Objekt, das einen Hinweis auf die Qualität des Ortes gibt.

Die Metadaten eines Ortes werden von einem supplier zur Verfügung gestellt, der verlangen kann, dass dem Benutzer eine attribution Nachricht angezeigt wird, wenn die Ortsdetails angezeigt werden.

Orte haben ein zugehöriges icon, das verwendet werden kann, um einen Ort auf einer Karte darzustellen oder um einen Delegierten in einer Ansicht zu dekorieren.

Orte können mit zusätzlichem Rich Content verknüpft sein. Zu den derzeit unterstützten Rich Content gehören redaktionelle Beschreibungen, Bewertungen und Bilder. Diese werden als eine Reihe von Modellen zum Abrufen der Inhalte dargestellt. Redaktionelle Beschreibungen des Ortes sind über die Eigenschaft editorialModel verfügbar. Bewertungen des Ortes sind über die Eigenschaft reviewModel verfügbar. Auf eine Bildergalerie des Ortes kann über die Eigenschaft imageModel zugegriffen werden.

Orte können zusätzliche Attribute haben, die nicht durch die formale API abgedeckt sind. Die Eigenschaft extendedAttributes ermöglicht den Zugriff auf diese. Die Art der verfügbaren erweiterten Attribute ist für jede Plugin spezifisch.

Ein Ort ist fast immer an eine plugin gebunden. Die Eigenschaft plugin muss gesetzt werden, bevor save(), remove() oder getDetails() aufgerufen werden können. Die Eigenschaften reviewModel, imageModel und editorialModel sind nur gültig, wenn die Eigenschaft plugin gesetzt ist.

Speichern eines Ortes

Wenn Plugin dies unterstützt, kann der Typ Place verwendet werden, um einen Ort zu speichern. Erstellen Sie zunächst einen neuen Ort und legen Sie seine Eigenschaften fest:

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
}

Rufen Sie dann die Methode save() auf:

    myPlace.save();

Die Eigenschaft status ändert sich zu Place.Saving und dann zu Place.Ready, wenn das Speichern erfolgreich war, oder zu Place.Error, wenn ein Fehler auftritt.

Wenn die Eigenschaft placeId gesetzt ist, wird das Backend einen bestehenden Ort aktualisieren, andernfalls wird ein neuer Ort erstellt. Bei Erfolg wird die Eigenschaft placeId mit dem Bezeichner des neu gespeicherten Ortes aktualisiert.

Vorbehalte

Die Places API ist derzeit nur für das Speichern von core Details ausgelegt. Das Speichern von umfangreichen Inhalten wie Bildern und Bewertungen oder Details wie Anbieter und Bewertung ist kein unterstützter Anwendungsfall. Normalerweise ignoriert ein Manager diese Felder beim Speichern und kann eine Warnmeldung ausgeben, wenn sie ausgefüllt sind.

Die Places API unterstützt nur das Speichern der folgenden Kerndetails:

• Name
• Ortskennung
• Standort
• Kontaktdetails
• Symbol
• Kategorien (tagähnliche Namen zur Beschreibung eines Ortes)
• Sichtbarkeitsbereich

Es ist möglich, dass Anbieter nur eine Teilmenge davon unterstützen. Weitere Einzelheiten finden Sie in der Plugin-Dokumentation.

Das Speichern von Eigenschaften wie die Bewertung, erweiterte Attribute, Bilder, Bewertungen, Leitartikel und Anbieter wird von der Places API ausdrücklich nicht unterstützt.

Speichern zwischen Plugins

Beim Speichern von Orten zwischen Plugins gibt es ein paar Dinge zu beachten. Einige Felder eines Ortes, wie z.B. die ID, Kategorien und Icons, sind Plugin-spezifische Entitäten. Zum Beispiel können die Kategorien in einem Manager nicht in einem anderen erkannt werden. Daher ist es nicht möglich, einen Ort direkt von einem Plugin in einem anderen zu speichern.

Im Allgemeinen wird empfohlen, das Speichern über Plugins hinweg wie das Speichern von favorites zu behandeln, wie im Abschnitt "Favoriten" erläutert. Es gibt jedoch auch einen anderen Ansatz, der darin besteht, einen neuen Ort zu erstellen, sein (Ziel-)Plugin festzulegen und dann die Methode copyFrom() zu verwenden, um die Details des ursprünglichen Ortes zu kopieren. Bei der Verwendung von copyFrom() werden nur die Daten kopiert, die vom Ziel-Plugin unterstützt werden; Plugin-spezifische Daten, wie z. B. die Ortsbezeichnung, werden nicht übernommen. Sobald der Kopiervorgang abgeschlossen ist, befindet sich der Ort in einem geeigneten Zustand, um gespeichert zu werden.

Der folgende Ausschnitt zeigt ein Beispiel für das Speichern eines Ortes in einem anderen Plugin unter Verwendung der Methode copyFrom:

var place = Qt.createQmlObject('import QtLocation; Place { }', parent);
place.plugin = destinationPlugin;
place.copyFrom(originalPlace);
place.save();

Entfernen eines Ortes

Um einen Ort zu entfernen, stellen Sie sicher, dass ein Place-Objekt mit einer gültigen placeId -Eigenschaft existiert und rufen Sie dessen remove()-Methode auf. Die Eigenschaft status ändert sich in Place.Removing und dann in Place.Ready, wenn das Speichern erfolgreich war, oder in Place.Error, wenn ein Fehler auftritt.

Favoriten

Die Places API unterstützt das Konzept der Favoriten. Favoriten werden in der Regel durch zwei Plugins implementiert, wobei das erste Plugin typischerweise eine Nur-Lese-Quelle von Orten ist (Ursprungs-Plugin) und ein zweites Lese-/Schreib-Plugin (Ziel-Plugin) verwendet wird, um Orte vom Ursprung als Favoriten zu speichern.

Jeder Ort hat eine Favoriten-Eigenschaft, die den entsprechenden Ort aus dem Ziel-Plugin enthalten soll (der Ort selbst stammt aus dem Ursprungs-Plugin). Da sowohl der ursprüngliche Ort als auch die Favoriten-Instanzen verfügbar sind, kann der Entwickler wählen, welche Eigenschaften dem Benutzer angezeigt werden sollen. Zum Beispiel kann der Favorit einen geänderten Namen haben, der anstelle des ursprünglichen Namens angezeigt werden soll.

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

Im Folgenden wird gezeigt, wie eine neue Favoriteninstanz gespeichert wird. Es erfolgt ein Aufruf zum Erstellen/Initialisieren der Favoriteninstanz und anschließend wird die Instanz gespeichert.

place.initializeFavorite(destinationPlugin);
//if necessary customizations to the favorite can be made here.
//...
place.favorite.save();

Im Folgenden wird das Entfernen von Favoriten demonstriert:

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;

Die PlaceSearchModel hat eine favoritesPlugin-Eigenschaft. Wenn die Eigenschaft gesetzt ist, werden alle Orte, die bei einer Suche gefunden werden, mit dem favoritesPlugin abgeglichen, um zu sehen, ob es einen entsprechenden Favoritenort gibt. Wenn ja, wird die favorisierte Eigenschaft des Ortes gesetzt, andernfalls bleibt die favorisierte Eigenschaft null.

Siehe auch PlaceSearchModel.

Eigenschaft Dokumentation

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

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

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

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

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

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

Methode Dokumentation