Erstellen Ihrer ersten SharePoint-Framework-Erweiterung (Hello World, Teil 1)

SharePoint-Framework -Erweiterungen (SPFx) sind clientseitige Komponenten, die im Kontext einer SharePoint-Seite ausgeführt werden. Sie können Erweiterungen für SharePoint Online bereitstellen und moderne JavaScript-Tools und -Bibliotheken verwenden, um sie zu erstellen.

Sie können die in diesem Artikel beschriebenen Schritte auch anhand des Videos in unserem YouTube-Kanal „Microsoft 365 Platform Communtiy Patterns & Practices (PnP)“ nachvollziehen:

Erstellen eines Erweiterungsprojekts

1. Erstellen Sie an einem Speicherort Ihrer Wahl ein neues Projektverzeichnis:

   md app-extension
   

2. Wechseln Sie in das Projektverzeichnis:

   cd app-extension
   

3. Führen Sie den SharePoint-Framework-Yeoman-Generator aus, um eine neue HelloWorld-Erweiterung zu erstellen.

   yo @microsoft/sharepoint
   

4. 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 der Lösung?: app-extension
   • Welchen Typ von clientseitiger Komponente möchten Sie erstellen?: Erweiterung
   • Welche Art von clientseitiger Erweiterung soll erstellt werden? Application Customizer
   • Wie lautet der Name des Application Customizer? HelloWorld

   Hinweis

   Wenn der verwendete Erweiterungsname zu lang ist, können Probleme auftreten. Mit den bereitgestellten Eingaben wird ein Aliaseintrag für die JSON-Manifestdatei des Application Customizer generiert. Falls der Alias mehr als 40 Zeichen enthält, wird eine Ausnahme ausgelöst, wenn Sie versuchen, die Erweiterung mit gulp serve --nobrowser zu verarbeiten. Sie können dieses Problem beheben, indem Sie den Aliaseintrag später aktualisieren.

   An diesem Punkt installiert Yeoman die erforderlichen Abhängigkeiten und erstellt ein Gerüst für die Lösungsdateien sowie die HelloWorld-Erweiterung. Das kann je nach Internetverbindung 1 bis 3 Minuten dauern.

5. Geben Sie als Nächstes Folgendes in die Konsole ein, um Visual Studio Code zu starten.

   code .
   

   Hinweis

   Da die clientseitige SharePoint-Lösung auf HTML/TypeScript basiert, können Sie zur Erstellung Ihrer Erweiterung jeden Code-Editor verwenden, der clientseitige Entwicklung unterstützt.

   Beachten Sie, wie die Standardlösungsstruktur wie die Lösungsstruktur für clientseitige Webparts aussieht. Dies ist die grundlegende SharePoint-Framework-Lösungsstruktur mit ähnlichen Konfigurationsoptionen über alle Lösungstypen hinweg.

   

6. Öffnen Sie ./src/extensions/helloWorld/HelloWorldApplicationCustomizer.manifest.json.

   Diese Datei definiert Ihren Erweiterungstyp und einen eindeutigen Bezeichner für Ihre Erweiterung. Sie benötigen diese ID später, wenn Sie Ihre Erweiterung debuggen und in SharePoint bereitstellen.

   {
     "$schema": "https://developer.microsoft.com/json-schemas/spfx/client-side-extension-manifest.schema.json",
   
      "id": "05966ad1-55c7-47f6-9ff5-4fee8bff838a",
      "alias": "HelloWorldApplicationCustomizer",
      "componentType": "Extension",
      "extensionType": "ApplicationCustomizer",
   
      // The "*" signifies that the version should be taken from the package.json
      "version": "*",
      "manifestVersion": 2,
      // If true, the component can only be installed on sites where Custom Script is allowed.
      // Components that allow authors to embed arbitrary script code should set this to true.
      // https://support.office.com/article/Turn-scripting-capabilities-on-or-off-1f2c515f-5d7e-448a-9fd7-835da935584f
      "requiresCustomScript": false
      }
   

Codieren des Anwendungsanpassers

Öffnen Sie die Datei ./src/extensions/helloWorld/HelloWorldApplicationCustomizer.ts.

Beachten Sie, dass die Basisklasse für den Application Customizer aus dem paket @microsoft/sp-application-base importiert wird, das SharePoint-Frameworkcode enthält, der vom Application Customizer benötigt wird.

import { Log } from '@microsoft/sp-core-library';
import {
    BaseApplicationCustomizer
} from '@microsoft/sp-application-base';
import { Dialog } from '@microsoft/sp-dialog';

Die Logik für den Anwendungsanpasser ist in der onInit()-Methode enthalten, die aufgerufen wird, wenn die clientseitige Erweiterung erstmalig auf der Seite aktiviert wird. Dieses Ereignis tritt nach Zuweisung von this.context und this.properties ein. Wie bei Webparts gibt onInit() eine Zusage zurück, die Sie verwenden können, um asynchrone Operationen auszuführen.

Im Folgenden werden die Inhalte von onInit() in der Standardlösung aufgelistet. Die Standardlösung schreibt ein Protokoll in das Dev Dashboard und zeigt dann beim Rendern der Seite eine einfache JavaScript-Warnung an.

public onInit(): Promise<void> {
  Log.info(LOG_SOURCE, `Initialized ${strings.Title}`);

  let message: string = this.properties.testMessage;
  if (!message) {
    message = '(No properties were provided.)';
  }

  Dialog.alert(`Hello from ${strings.Title}:\n\n${message}`);

  return Promise.resolve();
}

Wenn Ihr Application Customizer die JSON-Eingabe ClientSideComponentProperties verwendet, wird sie in das Objekt BaseExtension.properties deserialisiert. Sie können eine Benutzeroberfläche definieren, um sie zu beschreiben. Die Standardvorlage sucht nach einer Eigenschaft mit dem Namen testMessage. Wenn diese Eigenschaft bereitgestellt wird, wird diese in einer Warnmeldung ausgegeben.

Debuggen des Anwendungsanpassers

SharePoint-Framework-Erweiterungen können nicht mit der SharePoint Workbench getestet werden. Sie müssen sie mit einer SharePoint Online-Live-Website testen. Hierzu ist es jedoch nicht erforderlich, die Anpassung im App-Katalog bereitzustellen, um die Lösung zu testen, was das Debugging vereinfacht und beschleunigt.

1. Öffnen Sie die Datei ./config/serve.json.

   Beachten Sie, dass diese Datei mit den Standardeinstellungen aktualisiert wurde, die Ihrem Projekt entsprechen. Sie werden feststellen, dass unter dem customActions-Element eine bestimmte GUID erwähnt wird. Dies wird beim Erstellen eines Gerüsts für das Projekt automatisch entsprechend Ihrer Komponente aktualisiert. Wenn Sie neue Komponenten hinzufügen oder die Eigenschaften für die Komponente ändern, müssen Sie diese Datei zum Testen aktualisieren.

2. Aktualisieren Sie pageURL so, dass diese Ihrem eigenen Mandanten entspricht, den Sie zum Testen verwenden möchten. Sie können eine beliebige URL mit moderner Benutzeroberfläche verwenden. Beispielsweise: eine Willkommensseite einer neuen Teamwebsite, die mit einer Gruppe verknüpft ist, sodass die URL etwa folgendermaßen aussieht:

   https://sppnp.sharepoint.com/sites/yoursite/SitePages/Home.aspx

   Ihre serve.json-Datei sollte in etwa wie folgt aussehen (aktualisiert mit Ihren Mandantendetails):

   {
     "$schema": "https://developer.microsoft.com/json-schemas/core-build/serve.schema.json",
     "port": 4321,
     "https": true,
     "serveConfigurations": {
       "default": {
         "pageUrl": "https://sppnp.sharepoint.com/sites/mySite/SitePages/myPage.aspx",
         "customActions": {
           "54328ea6-0591-4fbd-aadb-5dc51fd53235": {
             "location": "ClientSideExtension.ApplicationCustomizer",
             "properties": {
               "testMessage": "Test message"
             }
           }
         }
       },
       "helloWorld": {
         "pageUrl": "https://sppnp.sharepoint.com/sites/mySite/SitePages/myPage.aspx",
         "customActions": {
           "54328ea6-0591-4fbd-aadb-5dc51fd53235": {
             "location": "ClientSideExtension.ApplicationCustomizer",
             "properties": {
               "testMessage": "Test message"
             }
           }
         }
       }
     }
   }
   

   Hinweis

   Die GUID im obigen JSON-Auszug ist die eindeutige ID der SPFx-Erweiterungskomponente. Dies ist im Manifest der Komponente definiert. Die GUID in Ihrer Lösung unterscheidet sich von einer eindeutigen Komponenten-ID.

3. Führen Sie den folgenden Befehl aus, um den Code zu kompilieren und die kompilierten Dateien auf Ihrem lokalen Computer zu hosten:

   gulp serve
   

   Wenn der Code fehlerfrei kompiliert wird, bietet er das resultierende Manifest aus https://localhost:4321 an und startet außerdem Ihren Standardbrowser mit den erforderlichen Abfrageparametern.

   

4. Wechseln Sie zu Ihrem Browser, und wählen Sie Debugskripts laden aus, um weiter Skripts von Ihrem lokalen Host zu laden.

   

   Das Dialogmeldung sollte nun auf Ihrer Seite angezeigt werden.

   

   Dieses Dialogfeld wird von der SharePoint-Framework-Erweiterung ausgelöst. Da Sie die testMessage-Eigenschaft als Teil der Debug-Abfrageparameter bereitgestellt haben, ist diese in der Warnmeldung enthalten. Sie können Ihre Erweiterungsinstanzen basierend auf den Clientkomponenteneigenschaften konfigurieren, die für die Instanz im Laufzeitmodus übergeben werden.

Nächste Schritte

Herzlichen Glückwunsch, Sie haben Ihre erste SharePoint Framework-Erweiterung erstellt!

Um mit dem Erstellen der Erweiterung fortzufahren, lesen Sie Verwenden von Seitenplatzhaltern aus dem Anwendungsanpasser (Hello World, Teil 2). Sie verwenden das gleiche Projekt und nutzen bestimmte Inhaltsplatzhalter zum Ändern der Benutzeroberfläche von SharePoint. Ihnen wird bereits aufgefallen sein, dass der Befehl gulp serve immer noch im Konsolenfenster ausgeführt wird (oder in Visual Studio Code, falls Sie den Editor verwenden). Sie können ihn einfach weiterlaufen lassen und zum nächsten Artikel wechseln.