Verwenden von Fluent UI React in Office-Add-Ins

Fluent UI React ist das offizielle Open-Source-JavaScript-Front-End-Framework, das entwickelt wurde, um Erfahrungen zu erstellen, die sich nahtlos in eine breite Palette von Microsoft-Produkten, einschließlich Microsoft 365-Anwendungen, einfügen. Es bietet stabile, aktuelle, barrierefreie, auf React basierende Komponenten, die mit CSS-in-JS in hohem Maße angepasst werden können.

Hinweis

In diesem Artikel wird die Verwendung von Fluent UI React im Kontext von Office-Add-Ins beschrieben. Es wird jedoch auch in einer Vielzahl von Microsoft 365-Apps und -Erweiterungen verwendet. Weitere Informationen finden Sie unter Fluent UI React und das Fluent UI Web Open Source-Repository.

In diesem Artikel wird beschrieben, wie Sie ein Add-In erstellen, das mit React erstellt wurde und Fluent UI React-Komponenten verwendet.

Erstellen eines Add-In-Projekts

Sie verwenden den Yeoman-Generator für Office-Add-Ins, um ein Add-In-Projekt zu erstellen, das React verwendet.

Installieren der erforderlichen Komponenten

• Node.js (die neueste Active LTS-Version). Besuchen Sie die Node.js-Website, um die richtige Version für Ihr Betriebssystem herunterzuladen und zu installieren.

• Die neueste Version von Yeoman und des Yeoman-Generators für Office-Add-Ins. Um diese Tools global zu installieren, führen Sie den folgenden Befehl an der Eingabeaufforderung aus.

  npm install -g yo generator-office
  

  Hinweis

  Selbst wenn Sie bereits den Yeoman-Generator installiert haben, empfehlen wir Ihnen, das npm-Paket auf die neueste Version zu aktualisieren.

• Office in Verbindung mit einem Microsoft 365-Abonnement (einschließlich Office im Internet).

  Hinweis

  Wenn Sie noch nicht über Office verfügen, können Sie sich über das Microsoft 365-Entwicklerprogramm für ein Microsoft 365 E5-Entwicklerabonnement qualifizieren. Weitere Informationen finden Sie in den FAQ. Alternativ können Sie sich für eine kostenlose 1-monatige Testversion registrieren oder einen Microsoft 365-Plan erwerben.

Erstellen des Projekts

Führen Sie den folgenden Befehl aus, um ein Add-In-Projekt mit dem Yeoman-Generator zu erstellen: Ein Ordner, der das Projekt enthält, wird dem aktuellen Verzeichnis hinzugefügt.

yo office

Hinweis

Wenn Sie den yo office-Befehl ausführen, werden möglicherweise Eingabeaufforderungen zu den Richtlinien für die Datensammlung von Yeoman und den CLI-Tools des Office-Add-In angezeigt. Verwenden Sie die bereitgestellten Informationen, um auf die angezeigten Eingabeaufforderungen entsprechend zu reagieren.

Wenn Sie dazu aufgefordert werden, geben Sie die folgenden Informationen an, um das Add-In-Projekt zu erstellen:

• Wählen Sie einen Projekttyp aus: Geben Sie an Office Add-in Task Pane project using React framework.
• Wählen Sie einen Skripttyp aus: Geben Sie entweder TypeScript oder an JavaScript.
• Wie soll Ihr Add-In heißen? My Office Add-in angeben.
• Which Office client application would you like to support? Geben Sie einen der Hosts an. (Die Screenshots in diesem Artikel verwenden Word. Das erste Ausführen des Projekts ist einfacher, wenn Sie Excel, PowerPointoder Wordauswählen. Siehe Ausprobieren.)

Es folgt ein Beispiel.

Nach Abschluss des Assistenten erstellt der Generator erstellt das Projekt und installiert unterstützende Node-Komponenten.

Erkunden des Projekts

Das Add-In-Projekt, das Sie mit dem Yeoman-Generator erstellt haben, enthält Beispielcode für ein einfaches Aufgabenbereich-Add-In. Wenn Sie die Komponenten Ihres Add-In-Projekts untersuchen möchten, öffnen Sie das Projekt in Ihrem Code-Editor, und überprüfen Sie die folgenden Dateien. Die Dateinamenerweiterungen hängen davon ab, welche Sprache Sie auswählen. TypeScript-Erweiterungen werden in Klammern gesetzt. Wenn Sie bereit sind, das Add-In zu testen, fahren Sie mit dem nächsten Abschnitt fort.

• Die Datei ./manifest.xml oder ./manifest.json im Stammverzeichnis des Projekts definiert die Einstellungen und Funktionen des Add-Ins. Weitere Informationen zur manifest.xml-Datei finden Sie unter Office-Add-Ins mit dem Nur-Add-In-Manifest. Weitere Informationen zur manifest.json Datei finden Sie unter Office-Add-Ins mit dem einheitlichen App-Manifest für Microsoft 365.

• Die Datei ./src/taskpane/taskpane.html enthält das HTML-Markup für den Aufgabenbereich und lädt die Office-JavaScript-Bibliothek. Außerdem wird getestet, ob das Webview-Steuerelement Fluent UI React v9 unterstützt, und wenn dies nicht der Fall ist, wird eine spezielle Meldung angezeigt.

• Die Datei ./src/taskpane/index.jsx (tsx) ist die Stammkomponente von React. Es lädt React und Fluent UI React, stellt sicher, dass die Office JavaScript-Bibliothek geladen wurde, und wendet das von Fluent definierte Design an.

• Die Datei ./src/taskpane/office-document.js (ts) enthält den Office JavaScript-API-Code, der die Interaktion zwischen dem Aufgabenbereich und der Office-Clientanwendung erleichtert.

• Der Ordner ./src/taskpane/components/ enthält die Dateien der React-Komponente *.jss (tsx), die die Benutzeroberfläche erstellen.

Probieren Sie es aus

1. Navigieren Sie zum Stammordner des Projekts.

   cd "My Office Add-in"
   

2. Führen Sie die folgenden Schritte aus, um den lokalen Webserver zu starten und das Add-In querzuladen.

   Hinweis

   • Office-Add-Ins sollten HTTPS und nicht HTTP verwenden, auch während der Entwicklung. Wenn Sie nach dem Ausführen eines der folgenden Befehle aufgefordert werden, ein Zertifikat zu installieren, akzeptieren Sie die Aufforderung, das Zertifikat zu installieren, das der Yeoman-Generator bereitstellt. Möglicherweise ist es auch erforderlich, dass Sie Ihre Eingabeaufforderung oder Ihr Terminal als Administrator ausführen, damit die Änderungen vorgenommen werden können.

   • Wenn Sie zum ersten Mal ein Office-Add-In auf Ihrem Computer entwickeln, werden Sie möglicherweise in der Befehlszeile aufgefordert, Microsoft Edge WebView eine Loopback-Ausnahme zu gewähren ("Allow localhost loopback for Microsoft Edge WebView?"). Wenn Sie dazu aufgefordert werden, geben Sie ein Y , um die Ausnahme zuzulassen. Beachten Sie, dass Sie Administratorrechte benötigen, um die Ausnahme zuzulassen. Nach der Genehmigung sollten Sie nicht mehr zu einer Ausnahme aufgefordert werden, wenn Sie in Zukunft Office-Add-Ins querladen (es sei denn, Sie entfernen die Ausnahme von Ihrem Computer). Weitere Informationen finden Sie unter "Wir können dieses Add-In nicht über localhost öffnen", wenn ein Office-Add-In geladen wird oder Fiddler verwendet wird.

     

   • Wenn Sie den Yeoman-Generator zum ersten Mal verwenden, um ein Office-Add-In zu entwickeln, öffnet Ihr Standardbrowser ein Fenster, in dem Sie aufgefordert werden, sich bei Ihrem Microsoft 365-Konto anzumelden. Wenn kein Anmeldefenster angezeigt wird und ein Querlade- oder Anmeldetimeoutfehler auftritt, führen Sie aus atk auth login m365.

   Tipp

   Wenn Sie Ihr Add-In auf einem Mac testen, führen Sie den folgenden Befehl aus, bevor Sie fortfahren. Wenn Sie diesen Befehl ausführen, wird der lokale Webserver gestartet.

   npm run dev-server
   

   • Um Ihr Add-In zu testen, führen Sie den folgenden Befehl im Stammverzeichnis Ihres Projekts aus. Dadurch wird der lokale Webserver gestartet und die Office-Hostanwendung mit dem geladenen Add-In geöffnet.

     npm start
     

     Hinweis

     Wenn Sie Ihr Add-In in Outlook testen, npm start querladen Sie das Add-In sowohl auf den Outlook-Desktop als auch auf Webclients. Weitere Informationen zum Querladen von Add-Ins in Outlook finden Sie unter Querladen von Outlook-Add-Ins zu Testzwecken.

   • Um Ihr Add-In in Excel, Word oder PowerPoint im Web zu testen, führen Sie den folgenden Befehl im Stammverzeichnis Ihres Projekts aus. Wenn Sie diesen Befehl ausführen, wird der lokale Webserver gestartet. Ersetzen Sie "{url}" durch die URL eines Word-Dokuments auf Ihrem OneDrive oder einer SharePoint-Bibliothek, für die Sie Berechtigungen haben.

     Hinweis

     Wenn Sie auf einem Mac entwickeln, schließen Sie diese in {url} einfache Anführungszeichen ein. Gehen Sie nicht unter Windows vor.

     npm run start -- web --document {url}
     

     Es folgen einige Beispiele.

     • npm run start -- web --document https://contoso.sharepoint.com/:t:/g/EZGxP7ksiE5DuxvY638G798BpuhwluxCMfF1WZQj3VYhYQ?e=F4QM1R
     • npm run start -- web --document https://1drv.ms/x/s!jkcH7spkM4EGgcZUgqthk4IK3NOypVw?e=Z6G1qp
     • npm run start -- web --document https://contoso-my.sharepoint-df.com/:t:/p/user/EQda453DNTpFnl1bFPhOVR0BwlrzetbXvnaRYii2lDr_oQ?e=RSccmNP

     Wenn Ihr Add-In im Dokument nicht quergeladen wird, querladen Sie es manuell, indem Sie die Anweisungen unter Manuelles Querladen von Add-Ins in Office im Web befolgen.

   Hinweis

   Wenn Sie zum ersten Mal (oder zum ersten Mal seit mehr als einem Monat) ein Office-Add-In auf Ihren Computer quergeladen haben, werden Sie aufgefordert, zuerst ein altes Zertifikat zu löschen und dann ein neues zu installieren. Stimmen Sie beiden Eingabeaufforderungen zu.

3. Eine WebView-Eingabeaufforderung "Beim Laden anhalten " wird angezeigt. Wählen Sie OK aus.

4. Wenn der Aufgabenbereich "Mein Office-Add-In" noch nicht geöffnet ist, wählen Sie die Registerkarte "Start" und dann im Menüband die Schaltfläche "Aufgabenbereich anzeigen" aus, um den Add-In-Aufgabenbereich zu öffnen.

   Hinweis

   Wenn Sie Ihr Add-In in Outlook testen, erstellen Sie eine neue Nachricht. Navigieren Sie dann zur Registerkarte "Nachrichten ", und wählen Sie im Menüband "Aufgabenbereich anzeigen " aus, um den Add-In-Aufgabenbereich zu öffnen.

5. Geben Sie Text in das Textfeld ein, und wählen Sie dann "Text einfügen" aus.

   

6. Wenn Sie bereit sind, den Entwicklungsserver zu beenden und das Add-In zu deinstallieren, führen Sie den folgenden Befehl aus.

   npm stop
   

Migrieren zu Fluent UI React v9

Wenn Sie über ein vorhandenes Add-In verfügen, das eine ältere Version von Fluent UI React implementiert, empfehlen wir die Migration zu Fluent UI v9. Anleitungen zum Migrationsprozess finden Sie unter Erste Schritte bei der Migration zu v9.

Problembehandlung

• Stellen Sie sicher, dass Ihre Umgebung für die Office-Entwicklung bereit ist, indem Sie die Anweisungen unter Einrichten Ihrer Entwicklungsumgebung befolgen.

• Der automatische npm install Schritt, den Yo Office ausführt, kann fehlschlagen. Wenn beim Ausführen npm startFehler auftreten, navigieren Sie in einer Eingabeaufforderung zum neu erstellten Projektordner, und führen Sie den Befehl manuell aus npm install. Weitere Informationen zu Yo Office finden Sie unter Erstellen von Office-Add-In-Projekten mit dem Yeoman-Generator.

• Möglicherweise werden Warnungen angezeigt, die bei der Ausführung npm install für den Yeoman-Generator oder das Projekt generiert werden. In den meisten Fällen können Sie diese Warnungen ignorieren. Sicherheits- oder Überwachungswarnungen erfordern eine gesonderte Bewertung. Beheben Sie Schwachstellen in Laufzeitabhängigkeiten oder Abhängigkeiten, deren Ursprung Sie nicht bestimmen können, bevor Sie sie in der Produktion bereitstellen. Manchmal sind Abhängigkeiten veraltet, und ihre Ersetzungen werden von anderen Paketen, von denen das Projekt abhängt, nicht unterstützt. Verwenden Sie das npm-check-updates Tool, um verfügbare Abhängigkeitsupdates zu überprüfen.

  • Führen Sie in der Eingabeaufforderung im Stammprojektverzeichnis aus npm i -g npm-check-updates. Dadurch wird das Tool global installiert.
  • Ausführen ncu , um verfügbare Updates zu melden , ohne package.json zu ändern.
  • Überprüfen Sie die vorgeschlagenen Versionen auf Kompatibilität, aktualisieren Sie nur die entsprechenden Abhängigkeitsbereiche in package.json, und führen Sie npm installdann aus. Beachten Sie, dass ncu -u Abhängigkeitsbereiche umgeschrieben werden und fehlerhafte Hauptversionsupgrades umfassen können.

  Weitere Informationen zu Warnungen beim Ausführen npm installfinden Sie unter Warnungen und Abhängigkeiten in der Node.js- und npm-Welt.

• Wenn die Add-In-Schaltfläche im Menüband nicht angezeigt wird (z. B. Aufgabenbereich anzeigen), wählen Sie auf der Registerkarte "Start" des Menübands die Schaltfläche "Add-Ins" und dann das Test-Add-In aus.

Siehe auch

• UX-Entwurfsmuster für Office-Add-Ins
• Fluent UI React
• Fluent UI GitHub-Repository