Übung: Erstellen einer SPFx Image Card ACE mit Bildkarussell

  • 20 Minuten

In dieser Übung erstellen Sie eine SharePoint Framework (SPFx) Adaptive Card Extension (ACE) mit der Vorlage Image Card, die Bilder anzeigt, die von einer der Kameras auf dem ausgewählten Mars-Rover aufgenommen wurden.

Voraussetzungen

Das Entwickeln von ACEs für Viva Connections erfordert einen Microsoft 365-Mandanten, SharePoint Online und Viva Connections, die in Ihrem Mandanten eingerichtet sind. Verwenden Sie die folgenden Ressourcen, um Ihren Mandanten vorzubereiten:

Außerdem müssen die erforderlichen Entwicklertools auf Ihrer Arbeitsstation installiert sein:

Wichtig

In den meisten Fällen ist die Installation der neuesten Versionen folgender Tools die beste Option. Die hier aufgeführten Versionen wurden verwendet, als dieses Modul veröffentlicht und zuletzt getestet wurde.

Erstellen des SPFx-Projekts

Öffnen Sie eine Eingabeaufforderung, und wechseln Sie zu einem Ordner, in dem Sie das SPFx-Projekt erstellen möchten. Führen Sie dann den SharePoint-Yeoman-Generator aus, indem Sie den folgenden Befehl ausführen:

yo @microsoft/sharepoint

Gehen Sie wie folgt vor, um die angezeigte Eingabeaufforderung abzuschließen:

  • Wie lautet der Name Ihrer Lösung?: AceImageViewer
  • Welche Art von clientseitiger Komponente soll erstellt werden?: Erweiterung für adaptive Karten
  • Welche Vorlage möchten Sie verwenden?: Bildkartenvorlage
  • Wie lautet der Name Ihrer Erweiterung für adaptive Karten?: AceImageViewer

Nach der Bereitstellung der für das Projekt erforderlichen Ordner installiert der Generator alle Abhängigkeitspakete, indem npm install automatisch ausgeführt wird. Wenn NPM das Herunterladen aller Abhängigkeiten abgeschlossen hat, öffnen Sie das Projekt in Visual Studio Code.

Hinzufügen öffentlicher Eigenschaften zur ACE-Komponente

Die ACE-Komponente, die Sie in dieser Übung erstellen, ruft Bilder ab und zeigt sie an, die von einem Marsrover mithilfe eines der NASA Open API-Endpunkte aufgenommen wurden.

Um die API aufzurufen, müssen wir drei Werte festlegen:

  • API-Schlüssel
  • den Mars-Rover zum Abrufen von Fotos für
  • der Mars Sol, ein Sonnentag auf dem Mars, um die Bilder für

All dies sind öffentliche und konfigurierbare Eigenschaften für für die ACE-Komponente.

Hinweis

Die NASA Open-APIs unterstützen die Verwendung eines Demo-API-Schlüssels oder das Erstellen eines kostenlosen API-Schlüssels. In dieser Übung wird davon ausgegangen, dass Sie den Demoschlüssel verwenden.

Für den Demoschlüssel gelten Ratenlimits, z. B. die maximale Anzahl von Anforderungen pro IP-Adresse in einer Stunde und einem Tag. Wenn Sie die Demo-API-Schlüsselgrenzwerte überschreiten, können Sie einen Schlüssel erstellen, der mit Ihrer E-Mail-Adresse verknüpft ist. Weitere Informationen finden Sie auf der Nasa Open APIs-Website.

Fügen Sie zunächst der ACE-Komponente die Eigenschaften hinzu.

  1. Suchen Sie die ACE-Klasse in der Datei ./src/adaptiveCardExtensions/aceImageViewer/AceImageViewerAdaptiveCardExtension.ts , und öffnen Sie sie in VS Code.

  2. Suchen Sie die IAceImageViewerAdaptiveCardExtensionProps Schnittstelle, und aktualisieren Sie sie so, dass sie die folgenden Eigenschaften enthält:

    export interface IAceImageViewerAdaptiveCardExtensionProps {
  title: string;
  nasa_api_key: string;
  nasa_rover: string;
  mars_sol: number;
}

Fügen Sie als Nächstes dem Eigenschaftenbereich die Eigenschaften hinzu:

  1. Suchen Sie die -Klasse in der Datei ./src/adaptiveCardExtensions/aceImageViewer/AceImageViewerPropertyPane.ts , und öffnen Sie sie in VS Code.

  2. Suchen Sie die import Anweisung, die die PropertyPaneTextField -Methode importiert. Fügen Sie dieser import Anweisung eine Auflistung zur PropertyPaneDropdown -Methode hinzu.

    import {
  IPropertyPaneConfiguration,
  PropertyPaneTextField,
  PropertyPaneDropdown    // << add
} from '@microsoft/sp-property-pane';

  3. Aktualisieren Sie die vorhandene getPropertyPaneConfiguration() Methode, um einen einzelnen Parameter zu akzeptieren, der den ausgewählten Rover angibt:

    public getPropertyPaneConfiguration(selectedRover: string = 'curiosity'): IPropertyPaneConfiguration { .. }

  4. Fügen Sie dem Array von groupFields im -Objekt, das in der -Methode zurückgegeben wird, die getPropertyPaneConfiguration() folgenden Felder hinzu:

    PropertyPaneTextField('nasa_api_key', {
  label: 'NASA API key'
}),
PropertyPaneDropdown('nasa_rover', {
  label: 'NASA Mars rover',
  options: [
    { index: 0, key: 'curiosity', text: 'Curiosity' },
    { index: 1, key: 'opportunity', text: 'Opportunity' },
    { index: 2, key: 'spirit', text: 'Spirit' }
  ],
  selectedKey: selectedRover
}),
PropertyPaneTextField('mars_sol', {
  label: 'Display photos from Mars day (Sol)'
})

Fügen wir dem Eigenschaftenbereich eine kleine Verbesserung hinzu: Die Dropdownauswahl für den Marsrover sollte standardmäßig auf den aktuell ausgewählten Rover festgelegt werden. Die Signatur der getPropertyPaneConfiguration() -Methode akzeptiert einen Eingabeparameter, den wir zum Festlegen verwenden können:

  1. Wechseln Sie zurück zur AceImageViewerAdaptiveCardExtension -Klasse, und suchen Sie die getPropertyPaneConfiguration() -Methode. Ersetzen Sie die vorhandene return Anweisung durch Folgendes:

    return this._deferredPropertyPane?.getPropertyPaneConfiguration(this.properties.nasa_rover);

Fügen Sie abschließend einige Standardwerte für die Eigenschaften hinzu, wenn die ACE-Komponente der Seite hinzugefügt wird:

  1. Suchen Sie die ACE-Klasse in der Datei ./src/adaptiveCardExtensions/aceImageViewer/AceImageViewerAdaptiveCardExtension.manifest.json und öffnen Sie sie in VS Code.

  2. Fügen Sie der vorhandenen Liste der Eigenschaften im -Objekt die preconfiguredEntries.properties folgenden Eigenschaften hinzu:

    "nasa_api_key": "DEMO_KEY",
"nasa_rover": "curiosity",
"nasa_sol": 1000

Hinzufügen des NASA-REST-API-Diensthilfsprogrammes

Fügen wir dem Projekt einen Dienst hinzu, um alle Lesevorgänge aus der NASA-REST Open-API zu verarbeiten.

Erstellen Sie eine neue Datei ./src/adaptiveCardExtensions/aceImageViewer/nasa.service.ts im Projekt, und fügen Sie ihr den folgenden Code hinzu:

import { AdaptiveCardExtensionContext } from '@microsoft/sp-adaptive-card-extension-base';
import { HttpClient } from '@microsoft/sp-http';

export interface IMarsRoverCamera {
  id: number;
  name: string;
  rover_id: number;
  full_name: string;
}

export interface IMarsRoverVehicle {
  id: number;
  name: string;
  landing_date: Date;
  launch_date: Date;
  status: string;
}

export interface IMarsRoverPhoto {
  id: number;
  sol: number;
  camera: IMarsRoverCamera;
  rover: IMarsRoverVehicle;
  img_src: string;
  earth_date: Date;
}

export const fetchRoverPhotos = async (
  spContext: AdaptiveCardExtensionContext,
  apiKey: string,
  rover: string,
  mars_sol: number): Promise<IMarsRoverPhoto[]> => {
  const results: { photos: IMarsRoverPhoto[] } = await (
    await spContext.httpClient.get(
      `https://api.nasa.gov/mars-photos/api/v1/rovers/${rover}/photos?sol=${mars_sol}&page=1&api_key=${apiKey}`,
      HttpClient.configurations.v1
    )
  ).json();

  return Promise.resolve(results.photos);
}

Aktualisieren des Status der ACE-Komponente

Nachdem die öffentlichen Eigenschaften und der Hilfsdienst erstellt wurden, aktualisieren wir nun den Zustand der Komponente, der zum Anzeigen von Daten in der Komponente verwendet wird.

  1. Suchen Sie die ACE-Klasse in der Datei ./src/adaptiveCardExtensions/aceImageViewer/AceImageViewerAdaptiveCardExtension.ts , und öffnen Sie sie in VS Code.

  2. Fügen Sie die folgende import-Anweisung nach den vorhandenen import-Anweisungen ein:

    import { isEmpty } from '@microsoft/sp-lodash-subset'
import {
  fetchRoverPhotos,
  IMarsRoverPhoto
} from './nasa.service';

  3. Suchen Sie die IAceImageViewerAdaptiveCardExtensionState Schnittstelle, und aktualisieren Sie sie so, dass sie die folgenden Eigenschaften enthält:

    export interface IAceImageViewerAdaptiveCardExtensionState {
  currentIndex: number;
  roverPhotos: IMarsRoverPhoto[];
}

  4. Aktualisieren Sie als Nächstes die onInit() -Methode in der AceImageViewerAdaptiveCardExtension -Klasse, um diese beiden Eigenschaften mit leeren Werten zu initialisieren:

    this.state = {
  currentIndex: 0,
  roverPhotos: []
};

  5. Fügen Sie in onInit()den folgenden Code hinzu, um Bilder aus der NASA-API abzurufen, wenn mindeste Eigenschaften festgelegt sind. Diese sollte unmittelbar vor dem vorhandenen return Promise.resolve();

    if (!isEmpty(this.properties.nasa_api_key) &&
    !isEmpty(this.properties.nasa_rover) &&
    !isEmpty(this.properties.mars_sol)){
  this.setState({ roverPhotos: await fetchRoverPhotos(
    this.context,
    this.properties.nasa_api_key,
    this.properties.nasa_rover,
    this.properties.mars_sol)
  });
}

  6. Die letzte Anweisung verwendet das await -Schlüsselwort, sodass Sie das async Schlüsselwort zur Deklaration der onInit() Methode hinzufügen müssen:

    public async onInit(): Promise<void> {

Lassen Sie uns ein weiteres Szenario behandeln: Wenn der Benutzer das ausgewählte nasa_rover oder mars_sol im Eigenschaftenbereich ändert, möchten wir die Bilder im Zustand aktualisieren. Fügen Sie dazu der -Klasse den AceImageViewerAdaptiveCardExtension folgenden Code hinzu. Sie wird ausgeführt, wenn sich eine Eigenschaft im Eigenschaftenbereich ändert:

protected onPropertyPaneFieldChanged(propertyPath: string, oldValue: any, newValue: any): void {
  if (propertyPath === 'nasa_rover' && newValue !== oldValue) {
    (async () => {
      this.setState({ roverPhotos: await fetchRoverPhotos(
        this.context,
        this.properties.nasa_api_key,
        newValue,
        this.properties.mars_sol)
      });
    })
  }

  if (propertyPath === 'mars_sol' && newValue !== oldValue) {
    (async () => {
      this.setState({ roverPhotos: await fetchRoverPhotos(
        this.context,
        this.properties.nasa_api_key,
        this.properties.nasa_rover,
        newValue)
      });
    })
  }
}

Aktualisieren der CardView

Nachdem die Komponente nun so eingerichtet wurde, dass Fotos von der REST-API abgerufen und im Zustand gespeichert werden, können Sie das Rendering aktualisieren, um die Fotos anzuzeigen. Beginnen Sie, indem Sie cardView aktualisieren.

  1. Suchen und öffnen Sie die Datei ./src/adaptiveCardExtensions/aceImageViewer/cardView/CardView.ts in VS Code.

  2. Fügen Sie einen Verweis auf die aus dem IActionArguments@microsoft/sp-adaptive-card-extension-base Paket importierte Schnittstelle hinzu:

    import {
  BaseImageCardView,
  IImageCardParameters,
  IExternalLinkCardAction,
  IQuickViewCardAction,
  ICardButton,
  IActionArguments  // << add
} from '@microsoft/sp-adaptive-card-extension-base';

  3. Aktualisieren Sie als Nächstes die schaltflächen, die in cardView angezeigt werden. CardView kann null, eine oder zwei Schaltflächen zurückgeben. Sie möchten zwei Schaltflächen anzeigen, vorherige und nächste Schaltflächen, wenn Sie sich nicht am Anfang oder Ende der Sammlung von Fotos befinden. Fügen Sie dies hinzu, indem Sie den Inhalt der cardButtons() Accessormethode durch den folgenden Code ersetzen:

    const cardButtons: ICardButton[] = [];

if (this.state.currentIndex !== 0) {
  cardButtons.push(<ICardButton>{
    title: '<',
    id: '-1',
    action: {
      type: 'Submit',
      parameters: {}
    }
  });
}
if (this.state.currentIndex !== (this.state.roverPhotos.length - 1)) {
  cardButtons.push(<ICardButton>{
    title: '>',
    id: '1',
    action: {
      type: 'Submit',
      parameters: {}
    }
  });
}

return (cardButtons.length === 0)
  ? undefined
  : (cardButtons.length === 1)
    ? [cardButtons[0]]
    : [cardButtons[0], cardButtons[1]];

  4. Ersetzen Sie als Nächstes den Inhalt der data() Accessormethode durch den folgenden Code. Dadurch wird ein Standardbild des Mars mit einigen Anweisungen zurückgegeben, wenn weder der Rover noch mars sol angegeben ist. Andernfalls wird das aktuelle Bild angezeigt:

    if (!this.properties.nasa_rover || !this.properties.mars_sol) {
  return {
    primaryText: `Select Mars rover and sol to display photos...`,
    imageUrl: 'https://upload.wikimedia.org/wikipedia/commons/thumb/0/0e/Tharsis_and_Valles_Marineris_-_Mars_Orbiter_Mission_%2830055660701%29.png/240px-Tharsis_and_Valles_Marineris_-_Mars_Orbiter_Mission_%2830055660701%29.png',
    imageAltText: `Select Mars rover and sol to display photos...`,
    title: this.properties.title
  }
} else {
  const rover = `${this.properties.nasa_rover.substring(0, 1).toUpperCase()}${this.properties.nasa_rover.substring(1)}`;
  const roverImage = this.state.roverPhotos[this.state.currentIndex];
  if (roverImage) {
    return {
      primaryText: `Photos from the Mars rover ${rover} on sol ${this.properties.mars_sol}`,
      imageUrl: roverImage.img_src,
      imageAltText: `Image ${roverImage.id} taken on ${roverImage.earth_date} from ${rover}'s ${roverImage.camera.full_name} camera.`,
      title: this.properties.title
    };
  } else {
    return {
      primaryText: `Please refresh the page to reload the rover photos`,
      imageUrl: '',
      imageAltText: '',
      title: this.properties.title
    }
  }
}

  5. Ersetzen Sie als Nächstes den Inhalt der onCardSelection() Accessormethode durch den folgenden Code. Dadurch wird unsere Schnellansicht geöffnet, die Sie in einem Moment aktualisieren, wenn die Karte ausgewählt ist.

    return {
  type: 'QuickView',
  parameters: {
    view: QUICK_VIEW_REGISTRY_ID
  }
};

  6. Implementieren Sie als Nächstes die onAction() -Methode, indem Sie der -Klasse den CardView folgenden Code hinzufügen. Dies wird immer dann ausgeführt, wenn eine Übermittlungsaktion in der Implementierung von CardView auftritt. Denken Sie daran, dass Sie in der cardButtons() -Methode die id -Eigenschaft für die Schaltflächen auf eine positive oder negative Zahl festlegen, um durch das Array von Bildern zu navigieren:

    public onAction(action: IActionArguments): void {
  if (action.type !== 'Submit') { return; }

  let currentIndex = this.state.currentIndex;
  this.setState({ currentIndex: currentIndex + Number(action.id) });
}

  7. Kommentieren Sie abschließend den folgenden Verweis auf das -Objekt aus, oder entfernen Sie sie strings :

    import * as strings from 'AceImageViewerAdaptiveCardExtensionStrings';

Aktualisieren der QuickView

Der letzte Schritt vor dem Testen der ACE-Komponente besteht darin, die QuickView zu aktualisieren. In diesem Szenario zeigt die Schnellansicht weitere Details zum aktuellen Foto an.

  1. Suchen und öffnen Sie die Datei ./src/adaptiveCardExtensions/aceImageViewer/quickView/QuickView.ts in VS Code.

  2. Fügen Sie den vorhandenen Importen die folgende import Anweisung hinzu:

    import { IMarsRoverPhoto } from '../nasa.service';

  3. Entfernen Sie die vorhandene IQuickViewData Schnittstelle.

  4. Ersetzen Sie alle verbleibenden Verweise auf IQuickViewData in der QuickView -Klasse durch IMarsRoverPhoto.

  5. Ersetzen Sie den Inhalt der data() Accessormethode durch Folgendes:

    return this.state.roverPhotos[this.state.currentIndex];

  6. Kommentieren Sie abschließend den folgenden Verweis auf das -Objekt aus, oder entfernen Sie sie strings :

    import * as strings from 'AceImageViewerAdaptiveCardExtensionStrings';

Aktualisieren Sie nun die Vorlage für adaptive Karten:

  1. Suchen und öffnen Sie die Datei ./src/adaptiveCardExtensions/aceImageViewer/quickView/template/QuickViewTemplate.json in VS Code.

  2. Ersetzen Sie den Inhalt der Vorlage durch den folgenden Code:

    {
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "version": "1.5",
  "type": "AdaptiveCard",
  "body": [
    {
      "type": "Image",
      "url": "${img_src}"
    },
    {
      "type": "TextBlock",
      "text": "${rover.name} rover image #${id}",
      "horizontalAlignment": "Center"
    },
    {
      "type": "TextBlock",
      "text": "Photo Details",
      "spacing": "Medium",
      "separator": true,
      "size": "Large",
      "weight": "Bolder"
    },
    {
      "type": "FactSet",
      "facts": [
        {
          "title": "Rover:",
          "value": "${rover.name}"
        },
        {
          "title": "Camera:",
          "value": "${camera.full_name}"
        },
        {
          "title": "Date taken:",
          "value": "${earth_date} (sol ${sol})"
        }
      ]
    }
  ]
}

Testen des dynamischen ACE

Testen Sie den ACE, um unseren Bildbrowser zu sehen!

Führen Sie in der Konsole die folgende Anweisung aus:

gulp serve --nobrowser

Navigieren Sie in einem Browser zur von SharePoint gehosteten Workbench auf der Website, auf der Sie den ACE testen möchten. Wenn die URL der Website beispielsweise lautet, lautet https://contoso.sharepoint.com/sites/MSLearningTeamdie URL für die gehostete Workbench https://contoso.sharepoint.com/sites/MSLearningTeam/_layouts/15/workbench.aspx.

Wählen Sie das + Symbol und dann aceImageViewer aus der Toolbox aus:

Screenshot der SPFx-Toolbox.

Beachten Sie, dass die Komponente standardmäßig das Bild von Mars verwendet. Das liegt daran, dass wir keinen Mars-Sol-Satz haben:

Screenshot: Standardmäßiges ACE CardView-Rendering.

Wie bei einem SPFx-Webpart können Sie mit der Maus auf die ACE-Komponente zeigen und das Stiftsymbol auswählen, um den Eigenschaftenbereich zu öffnen:

Screenshot der Bearbeitungsoberfläche für eine ACE.

Legen Sie mars sol auf 1000 fest, und schließen Sie den Eigenschaftenbereich, indem Sie das X in der oberen rechten Ecke und dann den Link Vorschau in der oberen rechten Ecke der oberen Navigation der Seite auswählen, um die Seite in den Anzeigemodus zu versetzen.

Verwenden Sie die bereitgestellten Schaltflächen in CardView, um durch die Bilder zu scrollen. Eine zugeschnittene Version des Bilds wird in der CardView-Karte angezeigt.

Screenshot des ausgewählten Bilds in cardView.

Wählen Sie mit der Maus eine beliebige Stelle auf der Karte aus, ohne eine der Schaltflächen auszuwählen. In der Schnellansicht wird das nicht bearbeitete Foto mit weiteren Details zum Zeitpunkt der Aufnahme angezeigt:

Screenshot des ausgewählten Bilds in der Schnellansicht.

In dieser Übung haben Sie eine SharePoint Framework (SPFx) Adaptive Card Extension (ACE) mit der Vorlage Image Card erstellt, die Bilder anzeigt, die von einer der Kameras auf dem ausgewählten Marsrover aufgenommen wurden.

Testen Sie Ihr Wissen

1.

Wie können Entwickler mit Aktionen umgehen, die in adaptiven Karten übermittelt werden?

2.

Welche der folgenden Aussagen zur cardButtons() -Methode ist falsch?

3.

Das Registrieren einer CardView oder QuickView mit dem zugehörigen Ansichtsnavigator ist nur erforderlich, wenn Sie Ansichten miteinander verketten möchten.