Erstellen Ihrer ersten SharePoint-Erweiterung für adaptive Karten

  • Artikel

Adaptive Kartenerweiterungen (Adaptive Card Extensions, ACEs) sind ein neuer SharePoint-Framework Komponententyp, mit dem Entwickler umfangreiche native Erweiterungen für Dashboards und SharePoint-Seiten Viva Connections erstellen können. Da Erweiterungen für adaptive Karten das Framework für adaptive Karten von Microsoft verwenden, um eine Benutzeroberfläche mit dem deklarativen JSON-Schema zu generieren, müssen Sie sich nur auf die Geschäftslogik Ihrer Komponente konzentrieren und das SharePoint-Framework (SPFx) verarbeiten lassen, damit Ihre Komponente gut aussieht und plattformübergreifend funktioniert.

Wichtig

Diese Tutorial geht davon aus, dass Sie die SPFx v1.13 installiert haben. Weitere Informationen zum Installieren von SPFx v1.13 finden Sie in den Veröffentlichungshinweisen von SharePoint-Framework v1.13.

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 ausführen, das Sie erstellt haben:

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

  • Möchten Sie Mandantenadministratoren erlauben, festzulegen, ob die Lösungen unmittelbar für alle Websites bereitgestellt werden, ohne die Bereitstellung von Features oder das Hinzufügen von Apps zu Websites? Ja
  • 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? HelloWorld
  • Wie lautet die Beschreibung Ihrer Erweiterung für adaptive Karten? Hello World-Beschreibung

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 der 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.

Tipp

Sie können den lokalen Webserver auch starten, ohne einen Browser zu starten, indem Sie das Argument nobrowser in den Befehl gulp serve einschließen. Sie möchten beispielsweise die Datei serve.json nicht in allen Projekten ändern, und stattdessen ein Lesezeichen verwenden, um Ihre gehostete Workbench zu starten.

gulp serve --nobrowser

Verarbeiten der ACE in der Workbench

Bevor Sie sich mit dem Code befassen, führen Sie die Gerüstausgabe aus, und sehen Sie sich an, wie eine Erweiterung für adaptive Karten aussieht.

Die innere Entwicklungsschleife mit ACEs ähnelt SPFx-Webparts. Wir können lokal bereitstellen und den Code auf der Workbench ausführen.

gulp serve

Sobald der lokale Webserver ausgeführt wird, navigieren Sie zur gehosteten Workbench: https://{tenant}.sharepoint.com/_layouts/15/workbench.aspx

Öffnen Sie die Webpart-Toolbox und wählen Sie Ihre ACE aus:

Wählen Sie die ACE aus der Toolbox aus

Erkunden der Kartenansicht

ACEs können auf zwei verschiedene Arten gerendert werden. Die erste Möglichkeit, wie eine ACE rendern kann, wird als Kartenansicht bezeichnet.

Beim Rendern auf einem Dashboard oder einer Seite werden ACEs immer in dieser Ansicht gestartet.

ACE in Kartenansicht gerendert

Erkunden der Schnellansicht

Die zweite Möglichkeit, wie eine ACE rendern kann, wird als Schnellansicht bezeichnet. Wenn Sie mit einer ACE interagieren, können ACEs eine größere, benutzerdefinierte Benutzeroberfläche starten.

Hinweis

Die ACE-Interaktion ist im Bearbeitungsmodus deaktiviert. Die Workbench oder Seite muss sich im Vorschaumodus oder Lesemodus befinden, um mit der ACE zu interagieren.

Schalten Sie die Workbench im Vorschaumodus um.

Festlegen des Vorschaumodus für die Workbench

Auswählen der Schaltfläche Schnellansicht auf der ACE:

Auswählen der Schaltfläche

Untersuchen des Gerüstcodes

Erkunden der Basisklasse

Suchen und öffnen Sie die folgende Datei in Ihrem Projekt: ./src/adaptiveCardExtensions/helloWorld/HelloWorldAdaptiveCardExtension.ts.

export default class HelloWorldAdaptiveCardExtension
  extends BaseAdaptiveCardExtension<IHelloWorldAdaptiveCardExtensionProps,IHelloWorldAdaptiveCardExtensionState> {
  // ...
}

Alle ACEs müssen von der BaseAdaptiveCardExtension-Klasse aus erweitert werden. Sie können optional zwei Generika implementieren:

  • TProperties: Ähnlich wie Webparts ist dies der Satz persistenter Eigenschaften der Komponente (Eigenschaftenbehälter).
  • TState: Eindeutig für ACEs und kann optional den Satz renderbarer Daten definieren.

Rendering von ACE

protected renderCard(): string | undefined {
  return CARD_VIEW_REGISTRY_ID;
}

Die renderCard()-Methode ist "virtual", die einen Zeichenfolgenbezeichner an eine registrierte Ansicht zurückgibt; weitere Informationen zur Registrierung von Ansicht später. Diese Methode wird während des ersten Renderings der Kartenansicht aufgerufen.

Wenn renderCard() nicht überschrieben wird, wird eine Standardkartenansicht gerendert.

Kommentieren Sie die renderCard()-Methode aus, und sehen Sie sich an, was geschieht:

/*
protected renderCard(): string | undefined {
  return CARD_VIEW_REGISTRY_ID;
}
*/

Ergebnisse des Kommentierens der renderCard()-Methode

Heben Sie die Auskommentierung der renderCard()-Methode auf, um zum ursprünglichen Zustand zurückzukehren.

Die Standardkartenansicht wird mit den folgenden Eigenschaften aus dem Manifest gerendert:

  • Symbol: iconProperty
  • Titel: title
  • Kartentext: description

Hinweis

Im Gegensatz zur Kartenansicht gibt es keine Standardschnellansicht.

Registrieren einer Ansicht für die ACE

Damit eine Ansicht verwendet werden kann, muss sie mit ihrem entsprechenden ViewNavigator registriert sein. Zwei ViewNavigators werden auf der ACE verfügbar gemacht: cardNavigator und quickViewNavigator:

this.cardNavigator.register(CARD_VIEW_REGISTRY_ID, () => new CardView());
this.quickViewNavigator.register(QUICK_VIEW_REGISTRY_ID, () => new QuickView());

Hinweis

Sie müssen eine Ansicht registrieren, bevor sie verwendet werden kann. Sie können dies innerhalb des Konstruktors der Klasse oder der onInit()-Methode tun.

Kartenansichten

Suchen und öffnen Sie die Datei: ./src/adaptiveCardExtensions/helloWorld/cardView/CardView.ts.

Kartenansichten müssen aus diesen Basisklassen erweitert werden:

  • BaseBasicCardView

    BaseBasicCardView

  • BaseImageCardView

    BaseImageCardView

  • BasePrimaryTextCardView

    BasePrimaryTextCardView

Jede dieser Ansichten wird unterschiedlich gerendert und weist unterschiedliche Einschränkungen hinsichtlich der Daten auf, die für die Vorlage bereitgestellt werden können.

Hinweis

Die Kartenansichten für Vorlagen für adaptive Karten sind festgelegt und können nicht geändert werden.

Darüber hinaus gibt es zwei Generika für die Objekte "properties" und "state", die von der Ansicht und der ACE gemeinsam verwendet werden.

  • TProperties: Die Eigenschaftenschnittstelle der Ansicht, die gleiche Schnittstelle, die von persistenten Eigenschaften der ACE verwendet wird (Eigenschaftenbehälter).
  • TState: Eindeutig für ACEs und kann optional den Satz renderbarer Daten definieren.

Hinweis

SPFx gibt Änderungen am Status der ACE automatisch an jede Ansicht weiter.

Der data-Getter ist die einzige Methode, die von einer Kartenansicht implementiert werden muss. Der Rückgabetyp ist für die übergeordnete Klasse der Ansicht eindeutig.

Die cardButtons-Eigenschaft bestimmt, wie viele Schaltflächen auf der Karte angezeigt werden und welche Aktion beim Klicken ausgeführt werden soll.

Wenn "cardButtons" nicht implementiert ist, werden auf der Karte keine Schaltflächen angezeigt.

Hinweis

Während die anfängliche Kartenansicht in der renderCard()-Methode der ACE festgelegt wird, wird die anfängliche Schnellansicht als Teil der Aktion parameters einer Schaltfläche festgelegt. Dadurch können zwei Schaltflächen potenziell verschiedene Ansichten öffnen.

Fügen Sie eine zweite Schaltfläche hinzu, indem Sie dem von der cardButtons()-Methode zurückgegebenen Array ein weiteres Objekt hinzufügen:

public get cardButtons(): [ICardButton] | [ICardButton, ICardButton] | undefined {
  return [
    {
      title: strings.QuickViewButton,
      action: {
        type: 'QuickView',
        parameters: {
          view: QUICK_VIEW_REGISTRY_ID
        }
      }
    },
    {
      title: 'Bing',
      action: {
        type: 'ExternalLink',
        parameters: {
          target: 'https://www.bing.com'
        }
      }
    }
  ];
}

Anfänglich gibt es keine Änderungen an der Karte. Das liegt daran, dass die Kartengröße Medium für BasePrimaryTextCardView nur eine Schaltfläche anzeigt. SPFx wählt das erste Element im Tupel aus.

  1. Ändern Sie die Kartengröße, indem Sie zum Eigenschaftenbereich wechseln und Largeauswählen.

    Auswählen der Kartengröße

    ACE-Karte

  2. Wenn Sie nun die Schaltfläche Bing auswählen, wird Bing in einer neuen Browserregisterkarte geöffnet.

Die onCardSelection()-Methode bestimmt, was geschieht, wenn auf die Karte geklickt wird. Wenn die onCardSelection()-Methode nicht implementiert ist, geschieht nichts, wenn auf die Karte geklickt wird.

  1. Ändern Sie die Kartenauswahl, um die Schnellansicht zu öffnen, indem Sie die onCardSelection()-Methode ändern:

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

  2. Wenn Sie jetzt die Karte auswählen, wird die Schnellansicht geöffnet.

ACE-Schnellansichten

Suchen und öffnen Sie die folgende Datei: ./src/adaptiveCardExtensions/helloWorld/quickView/QuickView.ts.

Schnellansichten müssen die Basisklasse BaseAdaptiveCardView erweitern. Es gibt drei optionale Generika, die definiert werden können:

  • TData: Der von der data()-Gettermethode zurückgegebene Typ.
  • TProperties: Ähnlich wie bei der Kartenansicht ist dies die gleiche Schnittstelle, die von persistenten Eigenschaften der ACE verwendet wird (Eigenschaftenbehälter).
  • TState Ähnlich wie bei der Kartenansicht ist dies der Satz zustandsbehafteter Daten, die die Ansicht rendern muss. TState muss Eigenschaften für die ACE-Statusschnittstelle freigeben.

Eine Schnellansicht hat mehr Kontrolle über das Vorlagenschema für adaptive Karten als eine Kartenansicht. Der template()-Getter muss gültige JSON-Vorlagen für adaptive Karten zurückgeben. SPFx-ACEs unterstützen die Vorlagenerstellung für adaptive Karten. Die Eigenschaften des Objekts, das vom data-Getter zurückgegeben wird, werden automatisch dem gebundenen Vorlagenslot zugeordnet.

So ist beispielsweise "${description}" an "this.properties.description" gebunden.

// QuickView.ts
public get data(): IQuickViewData {
  return {
    // ...
    description: this.properties.description
  };
}

// QuickViewTemplate.json.ts
{
  "type": "TextBlock",
  "text": "${description}",
  "wrap": true
}

Hinweis

Sie müssen die Bindungssyntax für adaptive Karten verwenden, die $ und {}-Klammern verwendet.

Lassen Sie uns dies ändern:

  1. Entfernen Sie die description-Eigenschaft aus den Schnellansichtsdaten, und fügen Sie zwei Schaltflächen hinzu.

  2. Aktualisieren Sie die IQuickViewData-Schnittstelle wie im folgenden Code gezeigt:

    export interface IQuickViewData {
  title: string;
  subTitle: string;
}

  3. Aktualisieren Sie die data()-Methode wie im folgenden Code gezeigt:

    public get data(): IQuickViewData {
  return {
    subTitle: this.state.subTitle,
    title: strings.Title
  };
}

  4. Suchen und öffnen Sie die folgende Datei: ./src/adaptiveCardExtensions/helloWorld/HelloWorldAdaptiveCardExtension.ts.

  5. Aktualisieren Sie die IHelloWorldAdaptiveCardExtensionState-Schnittstelle und onInit()-Methode wie folgt:

    export interface IHelloWorldAdaptiveCardExtensionState {
  subTitle: string;
}

..

public onInit(): Promise<void> {
  this.state = {
    subTitle: 'No button clicked'
  };
  // ...
}

entfernen Sie als nächstes den Verweis auf this.properties.description aus der Kartenansicht:

  1. Suchen und öffnen Sie die folgende Datei: ./src/adaptiveCardExtensions/helloWorld/cardView/CardView.ts.

  2. Entfernen Sie die description-Eigenschaft im zurückgegebenen Objekt:

    public get data(): IPrimaryTextCardParameters {
  return {
    primaryText: strings.PrimaryText
  };
}

Die Schnellansicht der von Ihnen erzeugten ACE gibt in ihrem template()-Getter das Objekt aus einer JSON-Datei zurück. Lassen Sie uns jetzt diese Vorlage ändern:

  1. Suchen und öffnen Sie die folgende Datei: ./src/adaptiveCardExtensions/helloWorld/quickView/template/QuickViewTemplate.json.

  2. Ersetzen Sie den Inhalt der Datei durch die folgende JASON:

    {
  "schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "version": "1.2",
  "body": [
    {
      "type": "TextBlock",
      "weight": "Bolder",
      "text": "${title}"
    },
    {
      "type": "TextBlock",
      "text": "${subTitle}",
      "wrap": true
    },
    {
      "type": "ActionSet",
      "actions": [
        {
          "type": "Action.Submit",
          "title": "Button One",
          "style": "positive",
          "data": {
            "id": "button1",
            "message": "Clicked Button One"
          }
        },
        {
          "type": "Action.Submit",
          "title": "Button Two",
          "data": {
            "id": "button2",
            "message": "Clicked Button Two"
          }
        }
      ]
    }
  ]
}

Testen Sie Ihre Änderungen, indem Sie die gehostete Workbench im Browser aktualisieren. Dies sollte die Änderungen übernehmen, die Sie auf das Projekt angewendet haben, wenn gulp serve noch ausgeführt wird:

Aktualisierte ACE-Schnellansicht

Tipp

Weitere Informationen zu adaptiven Karten finden Sie unter https://adaptivecards.io. Diese Website enthält auch einen Designer für adaptive Karten, mit dem Sie während dem Erstellen von adaptiven Karten eine Vorschau des Renderings und der Struktur anzeigen können.

An diesem Punkt haben Sie Ihre ACE so geändert, dass sie zwei neue Schaltflächen in die Schnellansichtskarte einschließt. Der nächste Schritt besteht darin, zu implementieren, was geschieht, wenn diese Schaltflächen ausgewählt werden. Dies erfolgt mit Aktionshandlern.

Aktionshandler

Aktionen werden von den Ansichten verarbeitet, in denen sie definiert sind.

Die Schnellansicht verfügt über zwei Schaltflächen, aber die Aktion Übermitteln wird derzeit von der Ansicht nicht verarbeitet. Die onAction()-Methode wird immer dann aufgerufen, wenn eine Aktion für adaptive Karten ausgeführt wird, z. B. wenn die Aktion Action.Submit initiiert wird.

Suchen und öffnen Sie die Datei QuickView.ts, und überschreiben Sie die onAction(), um die beiden Schaltflächenauswahlen zu behandeln, wie im folgenden Code gezeigt:

import { ISPFxAdaptiveCard, BaseAdaptiveCardView, IActionArguments } from '@microsoft/sp-adaptive-card-extension-base';

..

public onAction(action: IActionArguments): void {
  if (action.type === 'Submit') {
    const { id, message } = action.data;
    switch (id) {
      case 'button1':
      case 'button2':
        this.setState({
          subTitle: message
        });
        break;
    }
  }
}

Testen Sie Ihre Änderungen, indem Sie die gehostete Workbench im Browser aktualisieren. Dies sollte die Änderungen übernehmen, die Sie auf das Projekt angewendet haben, wenn gulp serve noch ausgeführt wird.

Wenn Sie eine der beiden Schaltflächen auswählen, wird der subTitle-Wert des Zustands auf den data.message-Wert festgelegt, was zu einem erneuten Rendern führt (weitere Informationen dazu später). Die adaptive Karte der Schnellansicht wird jetzt diese Meldung anzeigen, da ihre Vorlage mit subTitle verbunden ist.

Eigenschaftenbereich

Ähnlich wie Webparts können ACEs konfigurierbare Eigenschaften aufweisen, die von Benutzern mit entsprechenden Berechtigungen festgelegt werden. Diese ermöglichen es Ihnen, jede Implementierung Ihres ACE anzupassen. Dies erfolgt über den Eigenschaftenbereich.

ACEs können wie Webparts konfiguriert werden. Die API-Signaturen sind für die folgenden Methoden identisch, die sich in der Datei HelloWorldAdaptiveCardExtension.ts befinden:

  • getPropertyPaneConfiguration()
  • onPropertyPaneFieldChanged()

Das Standardgerüst für ACEs verwendet eine neue API, die darauf abzielt, die Paketgröße zu minimieren, wenn sich die Komponente nicht im Bearbeitungsmodus befindet. Die loadPropertyPaneResources()-Methode verwendet das Webpack-Segmentierungsfeature, um den für den Eigenschaftenbereich spezifischen Code in eine eigene JS-Datei zu unterteilen, die dann bei Bedarf geladen werden kann.

Zusätzlich zur Rückgabe der Konfiguration des Eigenschaftsbereichs wird die HelloWorldPropertyPane-Klasse verwendet, um die gesamte Logik des Bearbeitungsmodus zu kapseln.

Eigenschaften

Abgesehen vom Feld "Kartengröße" verfügt das Gerüst-ACE über drei (3) konfigurierbare Felder, die in getPropertyPaneConfiguration() der in der IHelloWorldAdaptiveCardExtension-Schnittstelle definierten Methode & definiert sind:

  • title
  • iconProperty
  • description

Kartenansichten sind so konzipiert, dass sie automatisch für alle Kartengrößen funktionieren. Abgesehen von der Angabe einer Standardkartengröße können ACEs diese Eigenschaft nicht steuern.

Die in der ACE-Datei (d. h. HelloWorldAdaptiveCardExtension.ts) definierten title- und iconProperty-Eigenschaften werden in den title()- bzw. iconProperty()-Getters des ACE verwendet, um den Titel und das Symbol der Karte zu konfigurieren:

Der title-Wert wird im Titel des Eigenschaftenbereichs und im Titel verwendet, der auf der Karte angezeigt wird.

public get title(): string {
  return this.properties.title;
}

Der iconProperty-Wert ist die URL des Symbols, das von Kartenansichten verwendet wird.

protected get iconProperty(): string {
  return this.properties.iconProperty || require('./assets/sharepointlogo.png');
}

Status

Die state-Eigenschaft muss vor dem Aufrufen der setState()-Methode initialisiert werden und kann nur einmal initialisiert werden.

public onInit(): Promise<void> {
  this.state = {
    subTitle: 'No button clicked'
  };
  // ...
}

Im Gegensatz zu "properties" wird "state" nicht über die aktuelle Sitzung hinaus beibehalten und sollte nur für den kurzlebigen Ansichtszustand verwendet werden.

Hinweis

Der ACE-Gerüst verwaltet eine description-Eigenschaft im state-Objekt. Dies ist überflüssig, da die ACE und alle ihre Ansichten einfach auf die descriptionverweisen können, die in properties gespeichert ist.

Erneutes Rendering

Das erneute Rendering erfolgt, wenn eine Eigenschaft im PropertyPane (Eigenschaftsbereich) aktualisiert wird oder wenn "setState()" aufgerufen wird.

Wenn Sie den Wert Beschreibungsfeld des Eigenschaftenbereichs aktualisieren, wird die Beschreibung auf der Karte aktualisiert. Sehen wir uns an, wie das geht:

  1. Suchen und öffnen Sie die folgende Datei: ./src/adaptiveCardExtensions/helloWorld/HelloWorldAdaptiveCardExtension.ts.

  2. Aktualisieren Sie als triviales Beispiel den subTitle-Wert, wenn die description während des onPropertyPaneFieldChanged-Ereignisses aktualisiert wird. Fügen Sie der ACE-Klasse HelloWorldAdaptiveCardExtension den folgenden Code hinzu:

    protected onPropertyPaneFieldChanged(propertyPath: string, oldValue: any, newValue: any): void {
  if (propertyPath === 'description') {
    this.setState({
      subTitle: newValue
    });
  }
}

Wenn Sie Partial<TState>-Objekt der setState()-Methode übergeben, werden alle Ansichten mit den neuen Werten aktualisiert. Wenn Sie das Beschreibungsfeld im Eigenschaftenbereich aktualisieren, wird nun der in der Schnellansicht angezeigte subTitle aktualisiert.

Wenn kein Wert oder identische Werte übergeben werden, erfolgt weiterhin ein erneutes Rendering.

Die setState()-Methode ist nicht nur auf den Eigenschaftenbereich beschränkt. Sie kann als Antwort auf den Empfang neuer Daten oder als Ergebnis einer Benutzeraktion verwendet werden.

Schlussbemerkung

Nach diesem Tutorial sollten Sie mit Folgendem vertraut sein:

  • Erstellen eines Gerüsts für eine Erweiterung für adaptive Karten
  • Registrieren von Ansichten
  • Ändern der Kartenansicht und der Schnellansicht
  • Grundlegende Aktionsbehandlung
  • Ändern des Eigenschaftenbereichs
  • Laden des Eigenschaftenbereichs verzögern
  • Verwendung von state
  • Unterschied zwischen properties und state