Übung: Erweitern des Viva Connections-Desktops mit Webparts

13 Minuten

In dieser Übung erstellen Sie ein SharePoint-Framework-Webpart, das Daten aus einer SharePoint-Liste abruft. Anschließend fügen Sie das Webpart dem Viva Connections-Desktop hinzu.

Erstellen einer neuen Lösung

Beginnen Sie damit, dass Sie mit dem Yeoman-Generator des SharePoint-Frameworks eine Lösung erstellen:

Erstellen Sie einen Ordner namens spfx-company-announcements-webpart für Ihr Projekt.
Ändern Sie in einem Terminal das Arbeitsverzeichnis in spfx-company-announcements-webpart.
Führen Sie den Befehl yo @microsoft/sharepoint aus, um mit dem Erstellen eines Gerüsts für eine neue Lösung zu beginnen.

Beantworten Sie die Eingabeaufforderungen des Generators:

Eingabeaufforderung	Eintrag
Wie lautet der Name Ihrer Lösung?	spfx-company-announcements-webpart
Nur SharePoint Online (neueste Version) wird unterstützt. Verwenden Sie für frühere Versionen von SharePoint (2016 und 2019) die Version 1.12.1 des Generators.	Nur SharePoint Online (aktuellste)
Wohin möchten Sie die Daten verschieben?	Verwenden Sie den aktuellen Ordner.
Möchten Sie den 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?	Nein
Benötigen die Komponenten in der Lösung Berechtigungen für den Zugriff auf eindeutige, nicht für andere Komponenten des Mandanten freigegebene Web-APIs?	Nein
Welchen Typ von clientseitiger Komponente möchten Sie erstellen?	WebPart
Wie lautet der Name Ihres Webparts?	Unternehmensankündigungen
Wie lautet die Beschreibung Ihres Webparts?	Zeigt Ankündigungen des Unternehmens an
Welches Framework möchten Sie verwenden?	Kein JavaScript-Framework:

Warten Sie, bis die Erstellung des Projekts fertig gestellt wurde. Das kann ein paar Minuten dauern.

Tipp

Während Sie warten, werden Ihnen wahrscheinlich Warnungen angezeigt. Diese können Sie unbesorgt ignorieren.

Installieren des Entwicklungszertifikats

Das SharePoint-Framework verwendet eine Workbench, die in SharePoint Online gehostet wird, in der Sie Ihren Code testen können, bevor Sie ihn in Viva Connections bereitstellen. Wenn Sie Ihren Code testen, starten Sie einen lokalen Webserver mittels Gulp. Die SharePoint-Framework-Workbench lädt dann Dateien von Ihrem lokalen Server, damit Sie sie testen können.

Damit die Workbench Dateien von Ihrem lokalen Entwicklungsserver laden kann, verwenden Sie das folgende Verfahren, um dem Entwicklungszertifikat aus dem SharePoint-Framework zu vertrauen.

Wichtig

Installieren Sie das Entwicklungszertifikat nur einmal auf Ihrem Computer. Wenn Sie ein neues Projekt erstellen, verwenden das SharePoint-Framework das zuvor installierte Zertifikat. Wenn Sie dies bereits getan haben, können Sie diese Schritte überspringen.

Öffnen Sie ein Terminal.
Ändern Sie das Arbeitsverzeichnisses in Ihren Projektordner.
Führen Sie den Befehl gulp trust-dev-cert aus.
Befolgen Sie die Anweisungen auf dem Bildschirm, um die Installation des Zertifikats abzuschließen.

Bearbeiten des Webparts

Nachdem Sie das Projekt erstellt haben, besteht der nächste Schritt darin, das Webpart so zu erweitern, dass es Ankündigungen des Unternehmens aus der Liste lädt und diese auf der Seite anzeigt:

Öffnen Sie das Projekt in einem Code-Editor.
Öffnen Sie im Code-Editor die Datei ./src/webparts/companyAnnouncements/CompanyAnnouncementsWebPart.ts.
Fügen Sie im oberen Abschnitt der Datei import { SPHttpClient } from '@microsoft/sp-http'; hinzu.
Löschen Sie den Code der Methode render.
Fügen Sie in der Methode render den folgenden Codeblock hinzu:
```
this.context.spHttpClient
  .get(`${this.context.pageContext.web.absoluteUrl}/_api/web/lists/getByTitle('Announcements')/items?$select=Title,Description,Important`,
    SPHttpClient.configurations.v1,
    {
      headers: {
        'accept': 'application/json;odata.metadata=none'
      }
    })
  .then(response => response.json())
  .then(announcements => {
    // todo: display results
  })
  .catch(error => this.context.statusRenderer.renderError(this.domElement, error));
```
Verwenden Sie den spHttpClient, um die Liste der Ankündigungen aus der zuvor erstellten Liste Ankündigungen abzurufen. spHttpClient umschließt die fetch-Standard-API und wird für das Aufrufen von SharePoint-APIs authentifiziert.

In der API-URL verwenden Sie den OData-Parameter $select, um die Liste der abzurufenden Eigenschaften anzugeben. Diese Eigenschaften stimmen mit den Spalten aus der Liste Ankündigungen überein.

Beim Aufrufen der SharePoint-API legen Sie außerdem den accept-Header so fest, dass Metadaten in der Antwort unterdrückt werden. Dadurch können Sie die Menge der über das Netzwerk gesendeten Daten verringern.

Nachdem Sie die Antwort von der API erhalten haben, rufen Sie die JSON-Antwort ab. Wenn beim Aufrufen der API ein Fehler auftritt, wird er mithilfe der vom Webpart verfügbar gemachten Hilfsmethode im Inhaltsbereich des Webparts angezeigt.
Nach dem Abrufen von Ankündigungen aus der Liste besteht der nächste Schritt darin, sie im Webpart anzuzeigen. Ersetzen Sie in der letzten then-Klausel den Kommentar // todo: display results durch den folgenden Block:
```
const announcementsHtml = announcements.value.map(announcement =>
  `<dt${announcement.Important ?
    ` class="${styles.important}"` : ''}>${announcement.Title}</dt>
  <dd>${announcement.Description}</dd>`);

this.domElement.innerHTML = `
<div class="${styles.companyAnnouncements}">
  <div class="${styles.container}">
    <div class="${styles.title}">Announcements</div>
    <dl>
      ${announcementsHtml.join('')}
    </dl>
  </div>
</div>
`;
```
Die Variable announcement enthält die Eigenschaft value, die ein Array von Ankündigungen aus der Liste umfasst. Für jede Ankündigung erstellen Sie eine HTML-Zeichenfolge mit den Elementen dt und dd, die den Inhalt der Ankündigung enthalten. Als Nächstes kombinieren Sie die Ankündigungen in einer einzelnen HTML-Zeichenfolge und zeigen sie im DOM-Element des Webparts an.

Tipp

Wenn möglich, sollten Sie immer semantischen HTML-Code anstelle der generischen Elemente div und span verwenden. Wenn Sie semantisches HTML verwenden, z. B. eine Überschrift (h1-h6) oder eine Definitionsliste (dl), hilft dies Personen, die Sprachausgaben und andere Barrierefreiheitstools verwenden, den Inhalten der Seite leichter zu folgen.
Um Ihre Änderungen zu speichern, wählen Sie "Datei>speichern" oder "STRG+S" auf der Tastatur (CMD+S unter macOS) aus.

Formatieren des Inhalts eines Webparts

Um Ankündigungen im Webpart anzuzeigen, haben Sie die Standard-HTML-Elemente dldt und dd verwendet. Sie haben außerdem eine benutzerdefinierte CSS-Klasse mit dem Namen important hinzugefügt, um wichtige Ankündigungen hervorzuheben. Fügen Sie nun CSS-Formatvorlagen hinzu, um zu formatieren, wie Ankündigungen und wichtige Ankündigungen angezeigt werden:

Öffnen Sie im Code-Editor die Datei ./src/webparts/companyAnnouncements/CompanyAnnouncementsWebPart.module.scss.
Ersetzen Sie den Inhalt der Datei durch den folgenden Code:
```
@import '~@microsoft/sp-office-ui-fabric-core/dist/sass/SPFabricCore.scss';

.companyAnnouncements {
  .container {
    @include ms-Grid;
    color: var(--primaryText, #323130);
  }

  .title {
    @include ms-fontSize-18;
    @include ms-fontWeight-semibold;
  }

  dt {
    @include ms-fontWeight-bold;
    @include ms-fontSize-14;
    margin-top: 1rem;

    &.important {
      color: $ms-color-red;
    }
  }

  dd {
    margin-left: 0;
  }
}
```
Sie beginnen mit dem Importieren der Fluent-Benutzeroberfläche, um eine konsistente Formatierung mit Microsoft 365 sicherzustellen. Als Nächstes fügen Sie eine CSS-Klasse für den Titel des Webparts hinzu. In der Klasse verweisen Sie auf die Schriftartdefinitionen aus der Fluent-Benutzeroberfläche. Anschließend definieren Sie die Formatierung für die Elemente dt und dd, die Sie zum Anzeigen von Ankündigungen verwendet haben.

Wie beim Titel des Webparts verweisen Sie auf die Formatvorlagen der Fluent-Benutzeroberfläche, um Konsistenz zu gewährleisten. Um wichtige Ankündigungen hervorzuheben, definieren Sie eine zusätzliche Klasse namens important, die roten Text verwendet, wie in der Fluent-Benutzeroberfläche definiert.
Um Ihre Änderungen zu speichern, wählen Sie "Datei>speichern" oder "STRG+S" auf der Tastatur (CMD+S unter macOS) aus.

Prüfen des Webparts

So erstellen Sie das Webpart für Unternehmensankündigungen und zeigen eine Vorschau davon an

Führen Sie im Terminal den Befehl gulp serve --nobrowser aus. Dieser Befehl startet einen lokalen Webserver unter https://localhost:4321.

Warnung

Wenn die folgende Warnung im Terminal angezeigt wird, bedeutet dies, dass der lokale Webserver Ihr Entwicklungszertifikat nicht laden konnte:

Warnung: [spfx-serve] Bei der Bereitstellung im HTTPS-Modus müssen ein PFX-Zertifikatpfad oder ein Zertifikatpfad und ein Schlüsselpfad angegeben werden, oder ein Entwicklungszertifikat muss generiert und vertrauenswürdig sein. Wenn kein SSL-Zertifikat bereitgestellt wird, wird ein selbstsigniertes Standardzertifikat verwendet. Erwarten Sie Browsersicherheitswarnungen.

Um dieses Problem zu beheben, beenden Sie den Webserver, indem Sie STRG+C drücken und den Befehl gulp trust-dev-cert ausführen.
Wechseln Sie in einem Webbrowser zur Workbench unter <Home site url>/_layouts/workbench.aspx. Die URL der Startsite ist der Ort, an dem Sie in der vorherigen Übung die Liste Ankündigungen erstellt haben.

Warnung

Wenn nach dem Öffnen der Workbench der folgende Fehler angezeigt wird, bedeutet dies, dass der lokale Webserver Ihr Entwicklungszertifikat nicht laden konnte:

Ihr Webpart wird nicht in der Toolbox angezeigt. Stellen Sie sicher, dass "gulp serve" in einem Webpartprojekt ausgeführt wird. Aktualisieren Sie die Seite, sobald "gulp serve" ausgeführt wird.

Um dieses Problem zu beheben, beenden Sie den Webserver, indem Sie STRG+C drücken und den Befehl gulp trust-dev-cert ausführen.
Zum Hinzufügen des neu erstellten Webparts zum Zeichenbereich wählen Sie die Schaltfläche + (Plus) aus, um die Toolbox zu öffnen.
Geben Sie in der Suchleiste Unternehmensankündigungen ein, und wählen Sie das Webpart aus.

Wenn Sie alle Schritte erfolgreich ausgeführt haben, werden Ihre Ankündigungen aus der Liste Ankündigungen in der Workbench angezeigt.

Die Titel der als wichtig ausgewählten Ankündigungen sind rot dargestellt.
Um den Entwicklungswebserver zu beenden, wechseln Sie zurück zum Terminal, und drücken Sie STRG+C.

Bereitstellen des Webparts in Viva Connections

Sie haben das Webpart Unternehmensankündigungen mithilfe des SharePoint-Frameworks erstellt. Jetzt können Sie es in Viva Connections bereitstellen.

So packen Sie das Webpart mithilfe von Gulp in eine App

Wechseln Sie zum Terminal, in dem das Arbeitsverzeichnis der Stammordner des Projekts ist.
Um die Lösung im Releasemodus zu erstellen, führen Sie den Befehl gulp bundle --ship aus.
Führen Sie den Befehl gulp package-solution --ship aus, um ein Releasemoduspaket der Lösung zu erstellen.

Die package-solution-Aufgabe erstellt eine App-Paketdatei namens spfx-company-announcements-webpart.sppkg im Ordner ./sharepoint/solution. Diese Datei ist Ihr App-Paket. Als Nächstes stellen Sie dieses Paket im SharePoint-App-Katalog bereit, der alle Viva Connections-Erweiterungen enthält.

Wenn es in Ihrem Mandanten keinen App-Katalog gibt, müssen Sie ihn jetzt erstellen:

Wechseln Sie in einem Webbrowser zum Microsoft 365 Admin Center.
Wählen Sie im seitlichen Menü die Option Alle anzeigen aus.
Wählen Sie in der Liste der Admin Center die Option SharePoint aus.
Wählen Sie im SharePoint Admin Center im seitlichen Menü Weitere Funktionen aus.
Wählen Sie im Abschnitt Apps die Schaltfläche Öffnen aus, um zur Administratorseite Apps zu wechseln.
Wählen Sie unter Apps den App-Katalog aus.
Wenn die Website geöffnet wird, verfügen Sie bereits über einen App-Katalog und können weitere Schritte überspringen.

Wenn der App-Katalog nicht vorhanden ist, werden Sie aufgefordert, einen zu erstellen.
Wählen Sie in der Liste der Optionen Automatisch eine neue App-Katalogwebsite erstellen und dann OK aus.

So stellen Sie Ihre Anwendung im Katalog bereit

Wechseln Sie in einem Webbrowser zum SharePoint-App-Katalog.
Wählen Sie im seitlichen Menü im Katalog Apps für SharePoint aus.
Ziehen Sie die Datei spfx-company-announcements-webpart.sppkg in die Liste.
SharePoint fordert Sie zur Bestätigung auf und stellt das Paket bereit. Wählen Sie Bereitstellen aus, um das Paket für die Installation auf SharePoint-Websites verfügbar zu machen.

Nachdem die App erfolgreich im App-Katalog bereitgestellt wurde, müssen Sie sie auf Ihrer Startsite installieren:

Wechseln Sie in einem Webbrowser zur Startsite.
Wählen Sie im oberen Menü das Symbol Einstellungen (Zahnrad) aus.
Wählen Sie im Abschnitt SharePoint den Link App hinzufügen aus.
Geben Sie im Suchfeld auf der Seite Meine Apps den Begriff Unternehmen (Company) ein, und suchen Sie die App spfx-company-announcements-webpart-client-side-solution.
Klicken Sie auf die Schaltfläche Hinzufügen.

Sie können jetzt das Webpart Unternehmensankündigungen auf jeder SharePoint-Seite auf der Website hinzufügen. So bearbeiten Sie das Webpart auf der Startseite der Startsite

Wechseln Sie in einem Webbrowser zur Startsite.
Um sicherzustellen, dass Sie sich auf der Startseite befinden, wählen Sie im oberen Menü Start aus.
Um die Seite zu bearbeiten, wählen Sie im Seitenmenü Bearbeiten aus.
Wählen Sie einen Bereich auf der Seite aus, in dem Sie das Webpart platzieren möchten.
Wählen Sie die Schaltfläche + aus, um die Toolbox zu öffnen.
Suchen Sie nach dem Webpart Unternehmensankündigungen.
Wählen Sie das Webpart aus, um es der Seite hinzuzufügen.
Wählen Sie im Seitenmenü Erneut veröffentlichen aus.

Das Webpart Unternehmensankündigungen befindet sich jetzt auf der Startseite Ihrer Startsite. Testen Sie die App, um zu sehen, wie dieses Webpart in Viva Connections in Microsoft Teams aussieht:

Öffnen Sie den Microsoft Teams-Desktopclient, oder wechseln Sie in einem Webbrowser zur Teams-Site.
Öffnen Sie die Viva Connection-App, und vergewissern Sie sich, dass im Webpart Unternehmensankündigungen alle Ankündigungen auf der Startseite der Startseite angezeigt werden.