Entwickeln von Office-Add-Ins mit Angular

Dieser Artikel erläutert, wie Sie mit Angular 2 und höher Office-Add-Ins als 1-Seiten-App erstellen.

Hinweis

Sie haben bereits Erfahrung mit der Erstellung von Office-Add-Ins in Angular und hätten weitere Tipps für uns? Sie können zu diesem Artikel in GitHub beitragen oder Ihr Feedback abgeben, indem Sie ein Problem im Repository übermitteln.

Ein Beispiel für ein mit dem Angular-Framework erstelltes Office-Add-In finden Sie unter Word Style Checking Add-in Built on Angular.

Installieren der TypeScript-Typdefinitionen

Öffnen Sie ein Node.js Fenster, und geben Sie Folgendes in der Befehlszeile ein.

npm install --save-dev @types/office-js

Bootstrapping muss im Inneren sein Office.initialize

Auf jeder Seite, die die Office JavaScript-APIs aufruft, muss Ihr Code zuerst eine Funktion Office.initializezuweisen. Office ruft diese Funktion sofort nach der Initialisierung der Office JavaScript-Bibliotheken auf. Wenn Sie keinen Initialisierungscode haben, kann der Funktionstext nur leere "{}"-Symbole sein, aber Sie dürfen die Office.initialize Funktion nicht undefiniert lassen. Weitere Informationen finden Sie unter Initialisieren Ihres Office-Add-Ins.

Ihr Angular Bootstrappingcode muss innerhalb der Funktion aufgerufen werden, die Sie zuweisenOffice.initialize. Dadurch wird sichergestellt, dass die Office-JavaScript-Bibliotheken zuerst initialisiert werden. Nachfolgend finden Sie ein einfaches Beispiel, das zeigt, wie Sie vorgehen müssen. Dieser Code sollte sich in der Standard.ts-Datei des Projekts befinden.

import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
import { AppModule } from './app.module';

Office.initialize = function () {
  const platform = platformBrowserDynamic();
  platform.bootstrapModule(AppModule);
};

Verwenden der Office-Dialogfeld-API mit Angular

Die Office-Add-In-Dialogfeld-API ermöglicht es Ihrem Add-In, eine Seite in einem nicht modalen Dialogfeld zu öffnen, das Informationen mit der Standard Seite austauscht, die sich normalerweise in einem Aufgabenbereich befindet.

Die displayDialogAsync-Methode verwendet einen Parameter, der die URL der Seite angibt, die im Dialogfeld geöffnet werden soll. Ihr Add-In kann über eine separate HTML-Seite (anders als die Basisseite) verfügen, die an diesen Parameter übergeben wird, oder Sie können die URL einer Route in Ihrer Angular-Anwendung übergeben.

Wenn Sie eine Route übergeben, ist es wichtig zu beachten, dass das Dialogfeld ein neues Fenster mit einem eigenen Ausführungskontext erstellt. Die Basisseite sowie ihr gesamter Initialisierungs- und Bootstrapping-Code werden erneut in diesem neuen Kontext ausgeführt, und alle Variablen werden im Dialogfeld auf ihre ursprünglichen Werte gesetzt. Mit dieser Technik wird eine zweite instance Ihrer Single-Page-Anwendung im Dialogfeld gestartet. Code, der Variablen im Dialogfeld ändert, ändert nicht die Aufgabenbereichversion der gleichen Variablen. Ebenso verfügt das Dialogfeld über einen eigenen Sitzungsspeicher (die Window.sessionStorage-Eigenschaft ), auf den nicht über Code im Aufgabenbereich zugegriffen werden kann.

Auslösen der UI-Aktualisierung

In einer Angular-App wird die Benutzeroberfläche manchmal nicht aktualisiert. Dies liegt daran, dass ein Teil des Codes außerhalb der Angular-Zone ausgeführt wird. Die Lösung besteht darin, den Code in der Zone abzulegen, wie im folgenden Beispiel gezeigt.

import { NgZone } from '@angular/core';

export class MyComponent {
  constructor(private zone: NgZone) { }

  myFunction() {
    this.zone.run(() => {
      // The codes that need update the UI.
    });
  }
}

Verwenden von Observable

Angular verwendet RxJS (Reactive Extensions for JavaScript), und RxJS führt Observable - und Observer -Objekte ein, um die asynchrone Verarbeitung zu implementieren. Dieser Abschnitt enthält eine kurze Einführung in die Verwendung von Observables. Ausführlichere Informationen finden Sie in der offiziellen RxJS-Dokumentation .

Ein Observable -Objekt ähnelt in gewisser Weise einem Promise -Objekt – es wird sofort von einem asynchronen Aufruf zurückgegeben, wird aber möglicherweise erst einige Zeit später aufgelöst. Während ein Promise jedoch ein einzelner Wert ist (der ein Arrayobjekt sein kann), ist ein Observable ein Array von Objekten (möglicherweise mit nur einem einzelnen Member). Dadurch kann Code Arraymethoden wie concat, mapund filterfür Observable -Objekte aufrufen.

Push statt Pull

Ihr Code "pullt" Promise Objekte, indem er sie Variablen zuweist, aber Observable Objekte "pushen" ihre Werte an Objekte, die dieObservableabonnieren. Die Abonnenten sind Observer Objekte. Der Vorteil der Pusharchitektur besteht darin, dass dem Array im Laufe der Observable Zeit neue Member hinzugefügt werden können. Wenn ein neues Element hinzugefügt wird, erhalten alle Objekte, die Observer die Observable abonnieren, eine Benachrichtigung.

Ist Observer so konfiguriert, dass jedes neue Objekt (als "nächstes" Objekt bezeichnet) mit einer Funktion verarbeitet wird. (Es ist auch so konfiguriert, dass auf einen Fehler und eine Abschlussbenachrichtigung reagiert wird. Ein Beispiel finden Sie im nächsten Abschnitt.) Aus diesem Grund Observable können Objekte in einer größeren Bandbreite von Szenarien als Promise Objekte verwendet werden. Neben der Rückgabe eines Observable aus einem AJAX-Aufruf kann beispielsweise die Art und Weise, wie Sie einen Promisezurückgeben können, von Observable einem Ereignishandler zurückgegeben werden, z. B. vom "changed"-Ereignishandler für ein Textfeld. Jedes Mal, wenn ein Benutzer Text in das Feld eingibt, reagieren alle abonnierten Observer Objekte sofort mit dem neuesten Text oder dem aktuellen Zustand der Anwendung als Eingabe.

Warten Sie, bis alle asynchronen Aufrufe abgeschlossen sind.

Wenn Sie sicherstellen möchten, dass ein Rückruf nur ausgeführt wird, wenn jedes Mitglied einer Gruppe von Promise-Objekten aufgelöst wurde, verwenden Sie die Methode Promise.all().

myPromise.all([x, y, z]).then(
  // TODO: Callback logic goes here.
)

Um dasselbe für ein Observable-Objekt sicherzustellen, müssen Sie die Methode Observable.forkJoin() verwenden.

const source = Observable.forkJoin([x, y, z]);

const subscription = source.subscribe(
  x => {
    // TODO: Callback logic goes here.
  },
  err => console.log('Error: ' + err),
  () => console.log('Completed')
);

Kompilieren der Angular-Anwendung mit dem Compiler „Ahead-of-Time (AOT)“

Die Leistung der Anwendung ist einer der wichtigsten Aspekte der Benutzerfreundlichkeit. Mit dem Compiler „Ahead-of-Time (AOT)“ können Sie eine Angular-Anwendung so optimieren, dass die Anwendung zum Zeitpunkt der Entwicklung kompiliert wird. Sämtlicher Quellcode (HTML-Vorlagen und TypeScript) wird in effizienten JavaScript-Code konvertiert. Wenn Sie Ihre Anwendung mit dem AOT-Compiler kompilieren, erfolgt zur Laufzeit keine zusätzliche Kompilierung, was zu einem schnelleren Rendering und zu schnelleren asynchronen Anforderungen für HTML-Vorlagen führt. Darüber hinaus wird die allgemeine Anwendungsgröße verkleinert, da der Angular-Compiler nicht in der Anwendungsdistribution enthalten sein muss.

Fügen Sie zum Verwenden des AOT-Compilers --aot zum ng build- oder ng serve-Befehl hinzu:

ng build --aot
ng serve --aot

Hinweis

Weitere Informationen zum Angular-Compiler „Ahead-of-Time (AOT)“ finden Sie im offiziellen Leitfaden.

Unterstützung des Trident-Webview-Steuerelements

Ältere Office-Clients verwenden das Trident-Webview-Steuerelement, das von Internet Explorer 11 bereitgestellt wird, wie unter Browser und Webview-Steuerelemente von Office-Add-Ins beschrieben. Es gibt einige Angular spezifische Überlegungen, wenn Ihr Add-In diese Office-Versionen unterstützen muss.

Angular hängt von einigen window.history Apis. Diese APIs funktionieren in der Trident-Webansicht nicht. Wenn diese APIs nicht funktionieren, funktioniert Ihr Add-In möglicherweise nicht ordnungsgemäß, z. B. kann es einen leeren Aufgabenbereich laden. Um dies zu vermeiden, werden diese APIs Office.js auf null gesetzt. Wenn Sie jedoch Office.js dynamisch laden, wird AngularJS möglicherweise vor Office.js geladen. In diesem Fall sollten Sie die window.history APIs deaktivieren, indem Sie der index.html Seite Ihres Add-Ins den folgenden Code hinzufügen.

<script type="text/javascript">window.history.replaceState=null;window.history.pushState=null;</script>

Wenn Ihr Add-In Trident-basierte Browsersteuerelemente unterstützt, müssen Sie die Hashspeicherortstrategie anstelle der Standardpfadspeicherortstrategie verwenden. Die Pfadspeicherortstrategie erfordert HTML5-Unterstützung, die Trident nicht bietet.