Erstellen einer Erweiterung für adaptive Karten mit Geolocation-Aktion

Hinweis

Diese Anleitung setzt voraus, dass Sie SPFx v1.14 installiert haben.

Weitere Informationen zur Installation von SPFx v1.14 finden Sie in den SharePoint Framework v1.14 Release Notes.

Erstellen eines Gerüsts für ein Projekt für Erweiterungen adaptiver Karten

Erstellen Sie ein neues Projektverzeichnis für Ihr Projekt, und ändern Sie Ihren aktuellen Ordner zu diesem Verzeichnis.

Erstellen Sie ein neues Projekt, indem Sie den Yeoman SharePoint-Generator aus dem neuen Verzeichnis heraus, das Sie erstellt haben, ausführen:

yo @microsoft/sharepoint

Wenn Sie dazu aufgefordert werden, geben Sie die folgenden Werte ein (wählen Sie für alle unten nicht aufgeführten Eingabeaufforderungen die Standardoption aus):

• Wie lautet der Name Ihrer Lösung? geolocation-tutorial
• Welchen Typ von clientseitiger Komponente möchten Sie erstellen? Erweiterung für adaptive Karten
• Welche Vorlage möchten Sie verwenden? Primäre Textvorlage
• Wie lautet der Name Ihrer Erweiterung für adaptive Karten? GeoLocation

An diesem Punkt installiert Yeoman die erforderlichen Abhängigkeiten und erstellt ein Gerüst für die Lösungsdateien. Dieser Vorgang kann einige Minuten dauern.

Aktualisieren Sie die URL der gehosteten Workbench Ihres Projekts.

Wenn Sie die gulp-Task serve verwenden, wird standardmäßig ein Browser mit der angegebenen URL der gehosteten Workbench gestartet, die in Ihrem Projekt angegeben ist. Die Standard-URL für die gehostete Workbench in einem neuen Projekt verweist auf eine ungültige URL.

• Suchen und öffnen Sie die Datei ./config/serve.json in Ihrem Projekt.

• Suchen Sie die Eigenschaft initialPage:

  {
    "$schema": "https://developer.microsoft.com/json-schemas/core-build/serve.schema.json",
    "port": 4321,
    "https": true,
    "initialPage": "https://enter-your-SharePoint-site/ _layouts/workbench.aspx"
  }
  

• Ändern Sie die enter-your-SharePoint-site-Domäne in die URL Ihres SharePoint-Mandanten und dessen Website, die Sie zu Testzwecken verwenden möchten. Zum Beispiel: https://contoso.sharepoint.com/sites/devsite/_layouts/workbench.aspx.

Wenn Sie dies tun gulp serve, wird die GeoLocation Karte angezeigt:

Hinzufügen von Geolocation-Aktionen zu Ihrer Adaptive Card Extension

An diesem Punkt haben wir den fertigen, gerüsteten Code. Lassen Sie uns nun versuchen, der Kartenansicht und der Schnellansicht Geolocation-Aktionen hinzuzufügen.

Wir werden eine Karte mit einer Kartenansicht und einer Schnellansicht erstellen. Auf der Kartenansicht werden wir eine Schaltfläche bereitstellen, die dem Benutzer seinen aktuellen Standort anzeigt, und durch Anklicken der Kartenansicht selbst wird eine Schnellansicht geöffnet.

In der Schnellansicht werden wir drei Schaltflächen bereitstellen, mit denen die folgenden Aktionen ausgeführt werden können:

• Abrufen des aktuellen Standorts des Benutzers
• Der Benutzer kann einen Ort auf der Karte auswählen
• Einen bestimmten Ort auf der Karte anzeigen

Aktualisieren Sie die Etiketten, die auf der Karte erscheinen werden

Bevor wir mit dem Hinzufügen der Aktionen beginnen, sollten wir zunächst die Zeichenfolgen aktualisieren, die auf der Karte zu sehen sind.

Suchen und öffnen Sie hierzu die folgende Datei in Ihrem Projekt: ./src/adaptiveCardExtensions/geoLocation/loc/en-us.js

Ersetzen Sie den Inhalt dieser Datei durch:

define([], function() {
  return {
    "PropertyPaneDescription": "Tutorial on geolocation action in ACE.",
    "TitleFieldLabel": "Geolocation",
    "Title": "GeoLocation",
    "SubTitle": "GeoLocation Actions",
    "PrimaryText": "Location Demo",
    "Description": "Demonstrating GeoLocation Capabilities",
    "ShowCurrentLocation": "My Location"
  }
});

Suchen und öffnen Sie als Nächstes die folgende Datei in Ihrem Projekt: ./src/adaptiveCardExtensions/geoLocation/loc/mystring.d.ts

Fügen Sie Folgendes hinzu:

ShowCurrentLocation: string;

an die IGeoLocationAdaptiveCardExtensionStrings Schnittstelle.

Hinzufügen von Aktionen in der Kartenansicht

Wie bereits erwähnt, werden wir in der Kartenansicht eine Schaltfläche hinzufügen, die dem Benutzer seinen aktuellen Standort anzeigt, und wenn er auf die Kartenansicht klickt, werden wir die Schnellansicht anzeigen.

Wir fügen zunächst die Funktionalität für die Schaltfläche in der Kartenansicht hinzu. Suchen und öffnen Sie hierzu die folgende Datei in Ihrem Projekt: ./src/adaptiveCardExtensions/geoLocation/cardView/CardView.ts

Ersetzen Sie hier die Definition der cardButtons Funktion durch die folgende:

public get cardButtons(): [ICardButton] | [ICardButton, ICardButton] | undefined {
  return [
    {
      title: strings.ShowCurrentLocation,
      action: {
        type: 'VivaAction.ShowLocation'
      }
    }
  ];
}

Mit dieser Änderung haben wir eine Schaltfläche mit Bezeichnung My Location konfiguriert, und die Klickaktion ist VivaAction.ShowLocation, die dem Benutzer den aktuellen Standort zeigt.

Ersetzen Sie als Nächstes den Inhalt onCardSelection Funktion durch Folgendes:

public get onCardSelection(): IQuickViewCardAction | IExternalLinkCardAction | undefined {
  return {
      type: 'QuickView',
      parameters: {
        view: QUICK_VIEW_REGISTRY_ID
      }
  };
}

Diese Änderung bedeutet, dass ein Benutzer, der auf die Kartenansicht klickt, eine Schnellansicht öffnen sollte.

Mit den bisher vorgenommenen Änderungen würde Ihre Kartenansicht wie folgt aussehen:

Hinzufügen von Aktionen in der Schnellansicht

In der Schnellansicht werden wir Schaltflächen für 3 Aktionen einführen:

• Abrufen des aktuellen Standorts des Benutzers
• Der Benutzer kann einen Ort auf der Karte auswählen
• Zeigen Sie einen bestimmten Ort auf der Karte an (in unserem Beispiel zeigen wir den Mount Everest)

Zusätzlich dazu gibt es zwei Textblöcke für die Anzeige Latitude und Longitude, die die jeweiligen Koordinaten anzeigen, wenn die VivaAction.GetLocation Aktion ausgeführt wird (mehr dazu später).

Zunächst definieren wir die Vorlage für die Schnellansicht. Suchen und öffnen Sie hierzu die folgende Datei in Ihrem Projekt: ./src/adaptiveCardExtensions/geoLocation/quickView/template/QuickViewTemplate.json

Ersetzen Sie den Inhalt dieser Datei durch den folgenden Text:

{
  "schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "version": "1.2",
  "body": [
    {
      "type": "TextBlock",
      "text": "${latitude}"
    },
    {
      "type": "TextBlock",
      "text": "${longitude}"
    }
  ],
  "actions": [
    {
      "title": "Choose location on map",
      "type": "VivaAction.GetLocation",
      "parameters": {
        "chooseLocationOnMap": true
      }
    },
    {
      "title": "Get my location",
      "type": "VivaAction.GetLocation"
    },
    {
      "title": "Show custom location",
      "type": "VivaAction.ShowLocation",
      "parameters": {
        "locationCoordinates": {
          "latitude": 27.98884062493244,
          "longitude": 86.9249751
        }
      }
    }
  ]
}

Damit stellen wir zwei Textblöcke bereit, um die Latitude und Longitude des Speicherorts anzuzeigen, den wir über VivaAction.GetLocation erhalten. Darüber hinaus haben wir drei Geolokalisierungsaktionen beschrieben.

Nachdem Sie diese Aktionen hinzugefügt haben, würde Ihre Schnellansicht wie folgt aussehen:

Richten Sie den Status für unsere Adaptive Card Extension ein

Bislang haben wir unsere Kartenansicht und Schnellansicht erstellt. Wenn Sie zu diesem Zeitpunkt eine gulp serve durchführen, können Sie die oben beschriebenen Aktionen ausführen.

Aber jetzt wollen wir noch einen Schritt weiter gehen.

Wir möchten nun die Koordinaten des aktuellen Standorts des Benutzers oder des vom Benutzer gewählten Standorts in der Schnellansicht anzeigen, wenn die entsprechenden Aktionen ausgeführt werden.

Dazu nutzen wir die beiden Textblöcke, die wir zuvor in der Datei QuickViewTemplate.json eingeführt hatten

Zu diesem Zweck werden wir zunächst neue Zustände einführen. Suchen und öffnen Sie zuerst die folgende Datei in Ihrem Projekt: ./src/adaptiveCardExtensions/geoLocation/GeoLocationAdaptiveCardExtension.ts

Fügen Sie hier der Schnittstelle states Folgendes IGeoLocationAdaptiveCardExtensionState hinzu:

latitude: string;
longitude: string;

Ändern Sie als Nächstes in der onInit Funktion this.state={} in

this.state = {
  latitude: 'TBD',
  longitude: 'TBD'
};

Wir werden nun ähnliche Änderungen auch in der Schnellansicht vornehmen.

Suchen und öffnen Sie die folgende Datei in Ihrem Projekt: ./src/adaptiveCardExtensions/geoLocation/quickView/QuickView.ts

Fügen Sie der IQuickViewData Schnittstelle die folgenden Eigenschaften hinzu:

latitude: string;
longitude: string;

und fügen Sie dann die folgenden beiden Zeilen im zurückgegebenen Objekt von data Getter hinzu:

latitude: "Latitude: " + this.state.latitude,
longitude: "Longitude: " + this.state.longitude

Implementieren Sie die Funktion onAction

Bisher haben wir unsere Geolocation-Aktionen definiert und in unseren Staaten verdrahtet. Jetzt können wir endlich die onAction Funktion implementieren, die dem Drittentwickler die Möglichkeit gibt, zu entscheiden, was er mit den Standortkoordinaten machen möchte, die der Benutzer ihm mitgeteilt hat.

Dazu öffnen Sie die Datei QuickView.ts (./src/adaptiveCardExtensions/geoLocation/quickView/QuickView.ts) und importieren die IGetLocationActionArguments Schnittstelle wie folgt:

import {IGetLocationActionArguments} from '@microsoft/sp-adaptive-card-extension-base';

Führen Sie abschließend die folgende onAction Funktion in der QuickView-Klasse ein:

public onAction(action: IGetLocationActionArguments): void {
  if (action.type === 'VivaAction.GetLocation') {
    this.setState({
      latitude: action.location.latitude.toString(),
      longitude: action.location.longitude.toString()
    });
  }
}

Wenn nun also die VivaAction.GetLocation Aktion über die Schnellansicht ausgelöst wird, übergibt das Framework für die adaptive Kartenerweiterung abhängig von den übergebenen Parametern entweder die aktuellen Koordinaten des Benutzers oder die vom Benutzer ausgewählten Koordinaten an den onAction Rückruf. In der oben gezeigten Implementierung wird geprüft, ob der action Typ vom Typ ist VivaAction.GetLocation, und wenn ja, wird die Schnellansicht neu dargestellt, indem ein setState, ausgeführt wird, in dem die Textblöcke latitude und longitude aktualisiert werden.

An diesem Punkt können Sie gulp serve erneut ausführen und sehen, wie alle bisher vorgenommenen Änderungen zusammengekommen sind.

Das ist es! Herzlichen Glückwunsch zur erfolgreichen Erstellung Ihrer adaptiven Kartenerweiterung mit Geolocation-Aktionen.