Standortfunktionen in der adaptiven Kartenerweiterung

Hinweis

Die Geolocation-Funktion in der Erweiterung für adaptive Karten ist in SPFx v1.15 verfügbar.

Stellen Sie also sicher, dass Sie es installiert haben, bevor Sie fortfahren.

Weitere Informationen zum Installieren der SPFx v1.15 Preview finden Sie unter Versionshinweise zu SharePoint-Framework v1.15.

In diesem Lernprogramm wird außerdem davon ausgegangen, dass Sie bereits eine SharePoint-Erweiterung für adaptive Karten erstellt haben.

Wie Sie Ihre erste SharePoint-Erweiterung für adaptive Karten erstellen, erfahren Sie in diesem Lernprogramm.

Neue Aktionstypen für Geolocation

Es gibt zwei Standortaktionen:

1. Standort abrufen
2. Standort anzeigen

Standort abrufen:

Teilt den aktuellen Gerätestandort eines Benutzers mit oder öffnet eine Standortauswahl und gibt den vom Benutzer ausgewählten Standort zurück. Im Browser wird Bing Maps als Zuordnungsschnittstelle verwendet.

Die ACE-Aktion für „Standort abrufen“ lautet: VivaAction.GetLocation.

Sie akzeptiert einen optionalen booleschen Parameter: ChooseLocationOnMap.

Wenn die Eigenschaft ChooseLocationOnMap auf true festgelegt ist, öffnet die Aktion eine Karte, und der Benutzer kann einen Standort auf der Karte auswählen. Andernfalls wird der aktuelle Gerätestandort des Benutzers abgerufen.

Standort anzeigen:

Mit dieser Aktion wird eine Karte auf dem Bildschirm angezeigt, auf der Sie entweder den aktuellen Standort des Benutzers auf der Karte oder Ihre angegebenen Koordinaten auf der Karte anzeigen können.

Die ACE-Aktion für „Standort anzeigen“ lautet: VivaAction.ShowLocation.

Sie akzeptiert einen optionalen Standortparameter: locationCoordinates.

Um einen bestimmten Standort anzuzeigen, sollten Sie die Standortkoordinaten (Breiten- und Längengrad) mithilfe des Parameters locationCoordinates übergeben.

Das locationCoordinates-Objekt besteht aus den folgenden Eigenschaften:

{
  /**
   * Latitude of the location.
   */
  latitude: number;

  /**
   * Longitude of the location.
   */
  longitude: number;

  /**
   * Timestamp (optional).
   */
  timestamp?: number;

  /**
   * Accuracy of the location (optional).
   */
  accuracy?: number;
}

Lernprogramm und Beispiele

Sie können sich dieses Lernprogramm ansehen, in dem schrittweise Details des Erstellens einer Karte mit Geolocation-Aktionen erläutert werden.

In den folgenden Beispielen werden die jeweilige Geolocation-Aktion und ihr Zweck beschrieben.

1. Abrufen des aktuellen Standorts des Benutzers

   Führen Sie in Ihrer JSON-Vorlage die folgende Aktion ein:

   "actions": [{
     type: 'VivaAction.GetLocation',
     id: 'Get Location'
   }]
   

   Wenn diese Aktion aufgerufen wird, wird die aktuelle Geolocation des Benutzers abgerufen und über den onAction-Rückruf an den Drittanbieterentwickler übergeben.

   Hinweis

   In diesem Fall wird die Karte nicht angezeigt.

2. Standort aus einer Karte abrufen

   Führen Sie in Ihrer JSON-Vorlage die folgende Aktion ein:

   "actions": [{
     type: 'VivaAction.GetLocation',
     id: 'Get Location',
     parameters: {chooseLocationOnMap: true}
   }]
   

   Wenn diese Aktion aufgerufen wird, wird eine Karte geöffnet, die den aktuellen Standort des Benutzers anzeigt, und der Benutzer kann den Standort seiner Wahl auswählen und freigeben. Die Koordinaten des ausgewählten Standorts werden über den onAction-Rückruf an den Drittanbieterentwickler übergeben.

3. Aktuellen Standort des Benutzers anzeigen

   Führen Sie in Ihrer JSON-Vorlage die folgende Aktion ein:

   "actions": [{
     type: 'VivaAction.ShowLocation',
     id: 'Show Location'
   }]
   

   Wenn diese Aktion aufgerufen wird, wird eine Karte mit den aktuellen Standortkoordinaten des Benutzers darauf angezeigt.

4. Angegebenen Standort anzeigen

   Führen Sie in Ihrer JSON-Vorlage die folgende Aktion ein:

   "actions": [{
     type: 'VivaAction.ShowLocation',
     id: 'Show Location',
     parameters: {
       locationCoordinates: {
         latitude: 28.6132039578389,
         longitude: 77.229488240066
       }
     }
   }]
   

   Wenn diese Aktion aufgerufen wird, wird eine Karte mit den in der Aktion angegebenen Standortkoordinaten darauf angezeigt.

Zugreifen auf Geolocation-Aktionen über den Eigenschaftenbereich der Karte im Karten-Designer

Wenn Sie keinen Code schreiben, aber dennoch sehen möchten, wie die Geolocation-Aktionen funktionieren, können Sie dieses Lernprogramm erkunden, in dem Sie Karten mit Geolocation-Aktionen über den Eigenschaftenbereich erstellen können.

Hinweis

Diese Geolocation-Aktionen können in der Kartenansicht oder den Schaltflächen der Kartenansicht bzw. innerhalb der Schnellansicht hinzugefügt werden.

Berechtigungs- und Fehlercodes

Damit die Standort-APIs funktionieren, muss der Benutzer die Berechtigung für den Zugriff auf den Standort des Geräts erteilen.

Fehlercode	Fehlerbeschreibung
PermissionDenied	Der Benutzer hat die Berechtigung für den Zugriff auf den Standort verweigert.
InternalError	Unerwarteter Fehler beim Aufrufen der Standort-APIs.
HostNotSupported	Die Standortaktion wird in einer nicht unterstützten Umgebung verwendet.

Rückrufe für Kartenentwickler

Wenn die Aktion VivaAction.GetLocation aufgerufen wird, übergeben wir die abgerufenen Standortkoordinaten über den onAction-Rückruf.

Hinweis

Der onAction-Rückruf wird für VivaAction.ShowLocationnicht aufgerufen.

Für die Aktionen VivaAction.GetLocation und VivaAction.ShowLocation wird, wenn der Benutzer in einen Fehlerzustand gelangt, wird ein onError-Rückruf aufgerufen, an den wir den Aktionsnamen und den Fehlercode übergeben.

Verfügbarkeit von Geolocation-Aktionen

Hinweis

Diese neuen Aktionen sind derzeit nur im Browser verfügbar. Viva Connections Desktop- und Viva Connections Mobile-Unterstützung wird später aktiviert. Nach der allgemeinen Verfügbarkeit sieht die Unterstützungsmatrix für Aktionen wie folgt aus:

Aktion	Viva Connection Desktop	Viva Connections Mobile	Browser
Standort abrufen	Nicht unterstützt	Unterstützt	Unterstützt
Standort anzeigen	Nicht unterstützt	Unterstützt	Unterstützt