Place QML Type

Der Typ „Ort“ steht für einen Standort, der von Interesse ist. Mehr...

• Liste aller Elemente, einschließlich geerbter Elemente

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

Ausführliche Beschreibung

Der Typ „Place“ stellt einen physischen Ort mit zusätzlichen Metadaten dar, die diesen Ort beschreiben. Im Gegensatz dazu dienen die Typen „ Location “, „ Address “ und „ geoCoordinate “ dazu, die Lage eines Ortes zu beschreiben. Die grundlegenden Eigenschaften eines „Place“ sind seine „ name “ und seine „ location “.

„Place“-Objekte werden in der Regel aus einem Suchmodell abgerufen und verfügen meist nur über ihre grundlegenden Eigenschaften. Mit der Eigenschaft „ detailsFetched “ lässt sich prüfen, ob weitere Eigenschaftswerte aus dem „ Plugin “ abgerufen werden müssen. Dies geschieht durch Aufruf der Methode „ getDetails()“. Der Fortschritt des Abrufvorgangs lässt sich mit der Eigenschaft „ status “ überwachen, die auf „Place.Fetching“ gesetzt wird, während die Details abgerufen werden.

Der Typ „Place“ verfügt über zahlreiche Eigenschaften, die Informationen zum Standort enthalten. Details zur Kontaktaufnahme mit dem Ort sind über die Eigenschaft „ contactDetails “ verfügbar. Außerdem stehen Komfort-Eigenschaften zum Abrufen des primären „ phone “, „ fax “, „ email “ und „ website “ zur Verfügung.

Jedem Ort werden null oder mehr „ categories “ zugewiesen. Kategorien werden in der Regel bei der Suche nach einer bestimmten Art von Ort verwendet, beispielsweise nach einem Restaurant oder einem Hotel. Einige Orte verfügen über ein „ ratings “-Objekt, das einen Hinweis auf die Qualität des Ortes gibt.

Die Metadaten eines Ortes werden von einem „ supplier “ bereitgestellt, der verlangen kann, dass dem Nutzer beim Aufrufen der Ortsdetails eine „ attribution “-Meldung angezeigt wird.

Orte sind mit einem „ icon “ verknüpft, der dazu verwendet werden kann, einen Ort auf einer Karte darzustellen oder einen Delegaten in einer Ansicht zu gestalten.

Orte können mit zusätzlichen Rich-Content-Elementen verknüpft sein. Zu den derzeit unterstützten Rich-Content-Elementen gehören redaktionelle Beschreibungen, Bewertungen und Bilder. Diese werden als eine Reihe von Modellen zum Abrufen der Inhalte bereitgestellt. 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 aufweisen, die nicht in der formalen API abgedeckt sind. Die Eigenschaft ` extendedAttributes ` bietet Zugriff auf diese. Die Art der verfügbaren erweiterten Attribute ist spezifisch für jeden ` Plugin`.

Ein „Place“ ist fast immer mit einem „ plugin “ verknüpft. Die Eigenschaft „ plugin “ muss gesetzt sein, bevor die Methoden „ save()“, „ remove()“ oder „ getDetails()“ aufgerufen werden können. Die Methoden „ reviewModel “, „ imageModel “ und „ editorialModel “ sind nur gültig, wenn die Eigenschaft „ plugin “ gesetzt ist.

Einen Ort speichern

Sofern das „ Plugin “ dies unterstützt, kann der Typ „Place“ zum Speichern eines Ortes verwendet werden. Erstellen Sie zunächst einen neuen „Place“ und legen Sie dessen 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 anschließend die Methode „ save()“ auf:

    myPlace.save();

Die Eigenschaft „ status “ ändert sich zunächst in „Place.Saving“ und anschließend in „Place.Ready“, wenn das Speichern erfolgreich war, oder in „Place.Error“, falls ein Fehler auftritt.

Ist die Eigenschaft „ placeId “ gesetzt, aktualisiert das Backend einen bestehenden Ort; andernfalls wird ein neuer Ort angelegt. Bei Erfolg wird die Eigenschaft „ placeId “ mit der Kennung des neu gespeicherten Ortes aktualisiert.

Einschränkungen

Die Places-API ist derzeit ausschließlich für das Speichern von „ core “-Angaben ausgelegt. Das Speichern von Rich-Content wie Bildern und Bewertungen oder von Details wie Anbieter und Bewertung wird nicht unterstützt. In der Regel ignoriert ein Manager diese Felder beim Speichern und gibt möglicherweise eine Warnmeldung aus, wenn sie ausgefüllt sind.

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

• Name
• Orts-ID
• Standort
• Kontaktdaten
• Symbol
• Kategorien (tagähnliche Bezeichnungen zur Beschreibung eines Ortes)
• Sichtbarkeitsbereich

Es ist möglich, dass Anbieter nur einen Teil davon unterstützen. Weitere Details finden Sie in der Plugin-Dokumentation.

Das Speichern von Eigenschaften wie Bewertung, erweiterte Attribute, Bilder, Bewertungen, redaktionelle Beiträge und Anbieter wird von der Places-API ausdrücklich nicht unterstützt.

Speichern zwischen Plugins

Beim Speichern von Orten zwischen Plugins gibt es einige Dinge zu beachten. Einige Felder eines Ortes, wie z. B. die ID, Kategorien und Symbole, sind pluginspezifische Entitäten. So werden beispielsweise die Kategorien in einem Manager möglicherweise in einem anderen nicht erkannt. Daher ist es nicht möglich, einen Ort direkt von einem Plugin in ein anderes zu speichern.

Es wird generell empfohlen, das Speichern zwischen Plugins wie das Speichern v favorites s zu handhaben, wie im Abschnitt „Favoriten“ erläutert. Es gibt jedoch einen anderen Ansatz: Man erstellt einen neuen Ort, legt dessen (Ziel-)Plugin fest und verwendet dann die Methode ` copyFrom()``, um die Details des ursprünglichen Ortes zu kopieren. Mit ` copyFrom()` werden nur Daten kopiert, die vom Ziel-Plugin unterstützt werden; plugin-spezifische Daten wie die Orts-ID werden nicht übernommen. Sobald der Kopiervorgang abgeschlossen ist, befindet sich der Ort in einem Zustand, in dem er gespeichert werden kann.

Der folgende Codeausschnitt zeigt ein Beispiel für das Speichern eines Ortes in einem anderen Plugin mithilfe der Methode ` copyFrom `:

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

Einen Ort entfernen

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

Favoriten

Die Places-API unterstützt das Konzept der Favoriten. Favoriten werden in der Regel mithilfe von zwei Plugins implementiert: Das erste Plugin ist typischerweise eine schreibgeschützte Quelle für Orte (Ursprungs-Plugin), während ein zweites Lese-/Schreib-Plugin (Ziel-Plugin) verwendet wird, um Orte aus dem Ursprungs-Plugin als Favoriten zu speichern.

Jeder „Place“ verfügt über eine „favorite“-Eigenschaft, die den entsprechenden Ort aus dem Ziel-Plugin enthalten soll (der Ort selbst stammt aus dem Ursprungs-Plugin). Da sowohl die ursprüngliche „Place“-Instanz als auch die „favorite“-Instanz verfügbar sind, kann der Entwickler auswählen, welche Eigenschaften dem Benutzer angezeigt werden sollen. Beispielsweise 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 wird ein Aufruf zum Erstellen/Initialisieren der Favoriteninstanz durchgeführt, 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 eines Favoriten veranschaulicht:

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;

Das „ PlaceSearchModel “ verfügt über eine „favoritesPlugin“-Eigenschaft. Ist diese Eigenschaft gesetzt, werden alle bei einer Suche gefundenen Orte mit dem „favoritesPlugin“ abgeglichen, um zu prüfen, ob ein entsprechender Favoritenort vorhanden ist. Ist dies der Fall, wird die „favorite“-Eigenschaft des „Place“ gesetzt, andernfalls bleibt die „favorite“-Eigenschaft auf null gesetzt.

Siehe auch „ PlaceSearchModel “.

Eigenschaftsdokumentation

attribution : string

Diese Eigenschaft enthält eine Rich-Text-Zeichenkette mit der Quellenangabe für den Ort. Einige Anbieter verlangen möglicherweise, dass die Quellenangabe dem Nutzer bei jeder Anzeige eines Ortes angezeigt wird. Der Inhalt dieser Eigenschaft sollte dem Nutzer angezeigt werden, sofern er nicht leer ist.

categories : list<Category> [read-only]

Diese Eigenschaft enthält die Liste der Kategorien, zu denen dieser Ort gehört. Welche Kategorien einem Ort zugewiesen werden können, ist für jeden plugin individuell festgelegt.

contactDetails : ContactDetails [read-only]

Diese Eigenschaft enthält die Kontaktdaten dieses Ortes, beispielsweise eine Telefonnummer oder eine Website-URL. Diese Eigenschaft ist eine Zuordnung von „ contactDetail “-Objekten.

detailsFetched : bool [read-only]

Diese Eigenschaft gibt an, ob die Details zum Ort bereits abgerufen wurden. Ist diese Eigenschaft auf „false“ gesetzt, wurden die Details zum Ort noch nicht abgerufen. Der Abruf kann durch Aufruf der Methode „ getDetails()“ erfolgen.

Siehe auch „ getDetails()“.

editorialModel : EditorialModel [read-only]

Diese Eigenschaft enthält ein Modell, mit dessen Hilfe redaktionelle Beschreibungen des Ortes abgerufen werden können.

extendedAttributes : ExtendedAttributes [read-only]

Diese Eigenschaft enthält die erweiterten Attribute eines Ortes. Erweiterte Attribute sind zusätzliche Informationen zu einem Ort, die nicht durch die Eigenschaften des Ortes abgedeckt sind.

favorite : Place

Diese Eigenschaft enthält die bevorzugte Instanz eines Ortes.

icon : Icon

Diese Eigenschaft enthält ein grafisches Symbol, mit dem der Ort dargestellt werden kann.

imageModel : ImageModel [read-only]

Diese Eigenschaft enthält ein Modell, mit dessen Hilfe Bilder des Ortes abgerufen werden können.

location : QtPositioning::Location

Diese Eigenschaft enthält den Standort des Ortes, anhand dessen die Koordinaten, die Adresse und der Begrenzungsrahmen abgerufen werden können.

name : string

Diese Eigenschaft enthält den Namen des Ortes, der zur Darstellung des Ortes verwendet werden kann.

placeId : string

Diese Eigenschaft enthält die eindeutige Kennung des Ortes. Die Ortskennung ist nur für den Plugin, der sie generiert hat, aussagekräftig und kann nicht zwischen Plugins übertragen werden. Es wird nicht garantiert, dass die Orts-ID universell eindeutig ist, sie ist jedoch innerhalb des Plugin, der sie generiert hat, eindeutig.

Ist lediglich die Ortskennung bekannt, können alle weiteren Ortsdaten von der Plugin abgerufen werden.

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

plugin : Plugin

Diese Eigenschaft enthält die ID „ Plugin “, die diesen Ort zuordnet und über die weitere Informationen zum Dienst abgerufen werden können.

primaryEmail : string [read-only]

Diese Eigenschaft enthält die primäre E-Mail-Adresse des Ortes. Wenn für diesen Ort keine Kontaktangabe vom Typ „E-Mail“ definiert ist, ist diese Eigenschaft eine leere Zeichenkette. Sie entspricht

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

primaryFax : string [read-only]

Diese Eigenschaft enthält die primäre Faxnummer des Ortes. Wenn für diesen Ort keine „Fax“-Kontaktdaten definiert sind, ist diese Eigenschaft eine leere Zeichenkette. Dies entspricht

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

primaryPhone : string [read-only]

Diese Eigenschaft enthält die Haupttelefonnummer des Ortes. Wenn für diesen Ort keine Kontaktangabe unter „Telefon“ definiert ist, ist diese Eigenschaft eine leere Zeichenkette. Dies entspricht:

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

primaryWebsite : string [read-only]

Diese Eigenschaft enthält die primäre Website-URL des Ortes. Wenn für diesen Ort keine Kontaktangabe „Website“ definiert ist, ist diese Eigenschaft eine leere Zeichenkette. Sie entspricht

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

ratings : Ratings

Diese Eigenschaft enthält Bewertungen des Ortes. Die Bewertungen geben Aufschluss über die Qualität eines Ortes.

reviewModel : ReviewModel [read-only]

Diese Eigenschaft enthält ein Modell, mit dessen Hilfe Bewertungen zu diesem Ort abgerufen werden können.

status : enumeration [read-only]

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

Der Status eines Ortes kann überprüft werden, indem die Status-Eigenschaft mit einer Handler-Funktion verknüpft wird und diese Handler-Funktion die Statusänderung verarbeitet.

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

supplier : Supplier

Diese Eigenschaft gibt den Anbieter der Ortsdaten an. Bei dem Anbieter handelt es sich in der Regel um ein Unternehmen oder eine Organisation, die die Daten zu diesem Ort erhoben hat.

visibility : enumeration

Diese Eigenschaft gibt die Sichtbarkeit des Ortes an. Mögliche Werte sind:

Beachten Sie, dass die Sichtbarkeit keinen Einfluss darauf hat, wie der Ort in der Benutzeroberfläche einer Anwendung auf dem Gerät angezeigt wird. Stattdessen definiert sie die Freigaberegeln für den Ort.

Methodendokumentation

void copyFrom(Place original)

Kopiert Daten aus einem „ original “-Ort in diesen Ort. Es werden nur Daten kopiert, die vom Plugin dieses Ortes unterstützt werden; pluginspezifische Daten wie die Ortskennung werden nicht kopiert.

string errorString()

Gibt eine Zeichenfolge zurück, die den Fehler der letzten Operation beschreibt. Wenn die letzte Operation erfolgreich abgeschlossen wurde, ist die Zeichenfolge leer.

void getDetails()

Diese Methode beginnt mit dem Abrufen von Ortsdetails.

Die Eigenschaft „ status “ ändert sich während des Abrufs in „Place.Fetching“. Bei erfolgreichem Abschluss werden die Eigenschaften des Objekts aktualisiert, „ status “ wird auf „Place.Ready“ gesetzt und „ detailsFetched “ wird auf „true“ gesetzt. Bei einem Fehler wird „ status “ auf „Place.Error“ gesetzt. Mit der Methode „ errorString()“ können die Details des Fehlers abgerufen werden.

void initializeFavorite(Plugin destinationPlugin)

Erstellt eine Favoriteninstanz für den Ort, der im Ziel-Plugin „ destinationPlugin “ gespeichert werden soll. Diese Methode führt keine Aktion aus, wenn die Eigenschaft „favorite“ nicht auf „ null “ gesetzt ist.

void remove()

Diese Methode führt eine Löschoperation für den Ort durch.

Die Eigenschaft „ status “ ändert sich während des Speichervorgangs in „Place.Removing“. Bei Erfolg wird „ status “ auf „Place.Ready“ gesetzt. Bei einem Fehler wird „ status “ auf „Place.Error“ gesetzt. Mit der Methode „ errorString()“ können die Details des Fehlers abgerufen werden.

void save()

Diese Methode führt einen Speichervorgang für den Ort durch.

Die Eigenschaft „ status “ ändert sich während des Speichervorgangs auf „Place.Saving“. Bei Erfolg wird die Eigenschaft „ status “ auf „Place.Ready“ gesetzt. Bei einem Fehler wird die Eigenschaft „ status “ auf „Place.Error“ gesetzt. Mit der Methode „ errorString()“ können die Details des Fehlers abgerufen werden.

War die Eigenschaft „ placeId “ zuvor leer, wird ihr bei einem erfolgreichen Speichervorgang automatisch ein gültiger Wert zugewiesen.

Beachten Sie, dass ein „ PlaceSearchModel “ die Methode „ Place::getDetails “ für jeden „Place“ aufruft, bei dem eine Aktualisierung festgestellt wird. Dies hat zur Folge, dass nach jeder erfolgreichen Speicherung eines „Place“ aus einem „ PlaceSearchModel “ die Details des „Place“ abgerufen werden, was zu einer Abfolge von Zustandsänderungen bei „ Saving “, „ Ready “, „ Fetching “ und „ Ready “ führt.