Verwenden von vorhandenen JavaScript-Bibliotheken in clientseitigen SharePoint-Framework-Webparts

Bei der Erstellung clientseitiger Webparts im SharePoint-Framework können Sie bereits vorhandene JavaScript-Bibliotheken nutzen, um leistungsstarke Lösungen zu programmieren. Sie sollten jedoch einige Aspekte berücksichtigen, damit Ihre Webparts die Leistung der SharePoint-Seiten, auf denen sie eingesetzt werden, nicht beeinträchtigen.

Referenzieren vorhandener Bibliotheken als Pakete

Am häufigsten werden bereits vorhandene JavaScript-Bibliotheken in clientseitigen SharePoint Framework-Webparts referenziert, indem sie als Paket im Projekt installiert werden.

1. Nehmen wir das Beispiel Angular. Um dieses Framework in einem clientseitigen Webpart zu verwenden, würden Sie Angular zunächst mithilfe von npm installieren:

   npm install angular --save
   

2. Um Angular mit TypeScript verwenden zu können, würden Sie mittels NPM Typendeklarationen installieren:

   npm install @types/angular --save-dev
   

3. Schließlich würden Sie Angular in Ihrem Webpart über die Anweisung import referenzieren:

   import { Version } from '@microsoft/sp-core-library';
   import {
     BaseClientSideWebPart,
     IPropertyPaneConfiguration,
     PropertyPaneTextField
   } from '@microsoft/sp-webpart-base';
   import { escape } from '@microsoft/sp-lodash-subset';
   
   import styles from './HelloWorld.module.scss';
   import * as strings from 'helloWorldStrings';
   import { IHelloWorldWebPartProps } from './IHelloWorldWebPartProps';
   
   import * as angular from 'angular';
   
   export default class HelloWorldWebPart extends BaseClientSideWebPart<IHelloWorldWebPartProps> {
     public render(): void {
       this.domElement.innerHTML = `
         <div class="${styles.helloWorld}">
           <!-- omitted for brevity -->
         </div>`;
   
         angular.module('helloworld', []);
   
         angular.bootstrap(this.domElement, ['helloworld']);
     }
   
     // omitted for brevity
   }
   

Bundling von Webpartressourcen

Das SharePoint-Framework arbeitet mit einer Buildtoolkette auf Basis von Open-Source-Tools wie gulp und webpack. Beim Erstellen von SharePoint-Framework-Projekten fassen diese Buildtools automatisch alle referenzierten Ressourcen in einer einzigen JavaScript-Datei zusammen. Dieser Prozess wird Bundling (Bündelung) genannt.

Bundling hat verschiedene Vorteile. Zunächst einmal sind alle erforderlichen Ressourcen für Ihr Webpart in einer einzigen JavaScript-Datei verfügbar. Das vereinfacht die Bereitstellung, da das Webpart nur aus einer einzigen Datei besteht und es unmöglich ist, während des Bereitstellungsprozesses eine Abhängigkeit zu übersehen.

Zudem verwendet Ihr Webpart unterschiedliche Ressourcen, und es ist wichtig, dass diese Ressourcen in der richtigen Reihenfolge geladen werden. Das während der Erstellung von webpack generierte Webpartbundle übernimmt das Laden der unterschiedlichen Ressourcen für Sie. Unter anderem löst es auch sämtliche Abhängigkeiten zwischen diesen Ressourcen auf.

Auch für Endbenutzer hat das Webpartbundling Vorteile: Im Allgemeinen lässt sich eine einzelne, größere Datei schneller herunterladen als viele kleine Dateien. Durch die Zusammenfassung mehrerer kleinerer Dateien in einem größeren Bundle lädt das Webpart schneller auf der Seite.

Ein Bundling von vorhandenen JavaScript-Bibliotheken mit clientseitigen SharePoint-Framework-Webparts hat allerdings auch Nachteile.

Beim Bundling vorhandener JavaScript-Frameworks im SharePoint-Framework werden alle referenzierten Skripts in der generierten Bundledatei zusammengefasst. Um noch einmal das Angular-Beispiel zu bemühen: Ein optimiertes Webpartbundle mit Angular ist über 170 KB groß.

Wenn Sie ein weiteres Webpart zu Ihrem Projekt hinzufügen, das ebenfalls Angular verwendet, und das Projekt erstellen, erhalten Sie zwei Bundledateien: eine pro Webpart. Jede Datei ist dabei größer als 170 KB.

Angenommen, Sie fügen diese Webparts zu einer Seite hinzu. Jeder Benutzer würde Angular dann mehrere Male herunterladen, und zwar einmal mit jedem Webpart auf der Seite. Dieser Ansatz ist ineffizient und verlangsamt das Laden der Seite.

Referenzieren vorhandener Bibliotheken als externe Ressourcen

Eine bessere Strategie ist es, vorhandene Bibliotheken als externe Ressourcen zu referenzieren und so in Ihr clientseitiges SharePoint-Framework-Webpart einzubinden. Auf diese Weise sind im Webpart nur die Skript-URLs vermerkt, jedoch keine weiteren Skriptinformationen. Wenn das Webpart zur Seite hinzugefügt wird, versucht es automatisch, alle erforderlichen Ressourcen über die angegebenen URLs zu laden.

Die Referenzierung vorhandener JavaScript-Bibliotheken im SharePoint Framework ist einfach und erfordert keine besonderen Codeänderungen. Da die Bibliothek zur Laufzeit von den angegebenen URLs geladen wird, muss sie nicht als Paket im Projekt installiert werden.

Nehmen wir wieder Angular als Beispiel: Um es als externe Ressource in Ihrem clientseitigen Webpart zu referenzieren, installieren Sie zunächst seine TypeScript-Typendeklarationen mithilfe von NPM:

npm install @types/angular --save-dev

Anschließend fügen Sie in der Datei config/config.json in der Eigenschaft externals den folgenden Eintrag hinzu:

"angular": {
  "path": "https://cdnjs.cloudflare.com/ajax/libs/angular.js/1.5.8/angular.min.js",
  "globalName": "angular"
}

Die vollständige Datei config/config.json würde dann in etwa so aussehen:

{
  "entries": [
    {
      "entry": "./lib/webparts/helloWorld/HelloWorldWebPart.js",
      "manifest": "./src/webparts/helloWorld/HelloWorldWebPart.manifest.json",
      "outputPath": "./dist/hello-world.bundle.js"
    }
  ],
  "externals": {
    "angular": {
      "path": "https://cdnjs.cloudflare.com/ajax/libs/angular.js/1.5.8/angular.min.js",
      "globalName": "angular"
    }
  },
  "localizedResources": {
    "helloWorldStrings": "webparts/helloWorld/loc/{locale}.js"
  }
}

Referenzieren Sie Angular in Ihrem Webpart:

import { Version } from '@microsoft/sp-core-library';
import {
  BaseClientSideWebPart,
  IPropertyPaneConfiguration,
  PropertyPaneTextField
} from '@microsoft/sp-webpart-base';
import { escape } from '@microsoft/sp-lodash-subset';

import styles from './HelloWorld.module.scss';
import * as strings from 'helloWorldStrings';
import { IHelloWorldWebPartProps } from './IHelloWorldWebPartProps';

import * as angular from 'angular';

export default class HelloWorldWebPart extends BaseClientSideWebPart<IHelloWorldWebPartProps> {
  public render(): void {
    this.domElement.innerHTML = `
      <div class="${styles.helloWorld}">
        <!-- omitted for brevity -->
      </div>`;

      angular.module('helloworld', []);

      angular.bootstrap(this.domElement, ['helloworld']);
  }

  // omitted for brevity
}

Wenn Sie Ihr Projekt jetzt erstellen, sehen Sie, dass die generierte Bundledatei nur noch 6 KB groß ist.

Wenn Sie ein weiteres Webpart zu Ihrem Projekt hinzufügen, das ebenfalls Angular verwendet, und das Projekt erneut erstellen, ist jedes Bundle 6 KB groß.

Die Annahme, dass Sie damit 300 KB eingespart haben, ist jedoch falsch. Beide Webparts benötigen Angular noch immer und laden es, sobald zum ersten Mal ein Benutzer die Seite besucht, auf der eines von ihnen platziert ist.

Auch wenn Sie beide Angular-Webparts zu der Seite hinzufügen, lädt SharePoint Framework Angular nur ein einziges Mal herunter.

Der wirkliche Vorteil einer Referenzierung vorhandener JavaScript-Bibliotheken als externe Ressourcen zeigt sich dann, wenn Ihre Organisation über einen zentralen Speicherort für alle häufig verwendeten Skripts verfügt oder Sie ein CDN nutzen. In solchen Fällen besteht die Möglichkeit, dass die betreffende JavaScript-Bibliothek sich bereits im Browsercache des Benutzers befindet. Dann müsste nur noch das Webpartbundle geladen werden, und dadurch würde die Ladezeit der Seite verkürzt.

Das vorangegangene Beispiel zeigt, wie Angular aus einem CDN geladen werden kann. Ein öffentliches CDN ist dabei jedoch nicht erforderlich. In der Konfiguration können Sie auf einen beliebigen Speicherort verweisen: ob öffentliches CDN, privat gehostetes Repository oder SharePoint-Dokumentbibliothek. Solange die Benutzer Ihrer Webparts auf die angegebenen URLs zugreifen können, werden die Webparts wie erwartet funktionieren.

CDNs sind für schnelle Ressourcenbereitstellung auf der ganzen Welt optimiert. Ein weiterer Vorteil beim Referenzieren von Skripts aus CDNs besteht daher darin, dass ein bestimmtes Skript möglicherweise bereits auf einer anderen Website verwendet wurde, die der Benutzer in der Vergangenheit besucht hat. Da das Skript dann bereits im Cache des lokalen Browsers liegen würde, müsste es nicht noch einmal speziell für Ihr Webpart heruntergeladen werden. Dadurch würde die Seite mit dem Webpart noch schneller laden.

Einige Organisationen verbieten den Zugriff auf öffentliche CDNs über das Firmennetzwerk. Dann ist ein privat gehosteter Speicherort für häufig verwendete JavaScript-Frameworks eine exzellente Alternative. Da Ihre Organisation in einem solchen Fall selbst die Bibliotheken hostet, kann sie auch die Cacheheader kontrollieren und die Ressourcenleistung eventuell noch weiter optimieren.

Formate von JavaScript-Bibliotheken

Die verschiedenen JavaScript-Bibliotheken werden jeweils unterschiedlich erstellt und gepackt. Einige werden als Module gepackt, andere bestehen aus einfachen Skripts, die im globalen Bereich ausgeführt werden. (Solche Skripts werden häufig auch als Nicht-Modul-Skripts bezeichnet.) Wenn Sie JavaScript-Bibliotheken über eine URL laden, hängt es vom Format des jeweiligen externen Skripts ab, wie Sie es in Ihrem SharePoint-Framework-Projekt registrieren müssen. Es gibt verschiedene Modulformate, beispielsweise AMD, UMD oder CommonJS; Sie müssen aber lediglich wissen, ob das betreffende Skript ein Modul ist oder nicht.

Bei der Registrierung von als Modul gepackten Skripts müssen Sie nur die URL angeben, von der das Skript heruntergeladen werden soll. Abhängigkeiten von anderen Skripts werden im Moduldesign des Skripts abgearbeitet.

Bei Nicht-Modul-Skripts müssen Sie mindestens die URL angeben, von der das Skript heruntergeladen werden soll, und den Namen der Variable, mit der das Skript im globalen Bereich registriert ist. Hängt das Nicht-Modul-Skript von anderen Skripts ab, können diese als Abhängigkeiten aufgeführt werden. Schauen wir uns dazu einige Beispiele an.

Angular v1.x ist ein Nicht-Modul-Skript. Wenn Sie es als externe Ressource in einem SharePoint Framework-Projekt angeben möchten, spezifizieren Sie seine URL und den Namen der globalen Variable, mit der es registriert werden soll:

"angular": {
  "path": "https://cdnjs.cloudflare.com/ajax/libs/angular.js/1.5.8/angular.min.js",
  "globalName": "angular"
}

Es ist wichtig, dass der in der globalName -Eigenschaft angegebene Name dem namen entspricht, der vom Skript verwendet wird. So kann es sich korrekt für andere Skripts verfügbar machen, die eventuell von ihm abhängen.

ngOfficeUIFabric ist ein UMD-Modul, das von Angular abhängt, und enthält die Angular-Richtlinien für Office UI Fabric. Die Abhängigkeit von Angular wird bereits im Modul abgearbeitet. Zur Registrierung müssen Sie also nur die Modul-URL angeben:

"ng-office-ui-fabric": "https://cdnjs.cloudflare.com/ajax/libs/ngOfficeUiFabric/0.12.3/ngOfficeUiFabric.js"

jQuery ist ein AMD-Skript. Zur Registrierung reicht daher diese einfache Codezeile:

"jquery": "https://code.jquery.com/jquery-2.2.4.js"

Angenommen, Sie möchten jQuery mit einem jQuery-Plug-In verwenden, das als Nicht-Modul-Skript verteilt wird,

Wenn Sie zur Registrierung beider Skripts den nachfolgenden Code verwendet haben, würde das Laden des Webparts höchstwahrscheinlich fehlschlagen. Beide Skripts würden wahrscheinlich parallel geladen werden, und das Plug-In könnte sich nicht bei jQuery registrieren.

"jquery": "https://code.jquery.com/jquery-2.2.4.js",
"simpleWeather": {
  "path": "https://cdnjs.cloudflare.com/ajax/libs/jquery.simpleWeather/3.1.0/jquery.simpleWeather.min.js",
  "globalName": "jQuery"
}

Wie bereits erwähnt, können Sie im SharePoint-Framework Abhängigkeiten für Nicht-Modul-Plug-Ins angeben. Diese Abhängigkeiten werden in der Eigenschaft globalDependencies angegeben:

"jquery": "https://code.jquery.com/jquery-2.2.4.js",
"simpleWeather": {
  "path": "https://cdnjs.cloudflare.com/ajax/libs/jquery.simpleWeather/3.1.0/jquery.simpleWeather.min.js",
  "globalName": "jQuery",
  "globalDependencies": [ "jquery" ]
}

Jede in der Eigenschaft globalDependencies angegebene Abhängigkeit muss auf eine andere Abhängigkeit im Abschnitt externals in der Datei config/config.json verweisen.

Wenn Sie jetzt versuchen, das Projekt zu erstellen, würde wieder ein Fehler gemeldet. Dieses Mal würde moniert, dass Sie keine Abhängigkeit zu einem Nicht-Modul-Skript angeben dürfen.

Um dieses Problem zu lösen, müssen Sie jQuery lediglich als Nicht-Modul-Skript registrieren:

"jquery": {
  "path": "https://code.jquery.com/jquery-2.1.1.min.js",
  "globalName": "jQuery"
},
"simpleWeather": {
  "path": "https://cdnjs.cloudflare.com/ajax/libs/jquery.simpleWeather/3.1.0/jquery.simpleWeather.min.js",
  "globalName": "jQuery",
  "globalDependencies": [ "jquery" ]
}

So legen Sie fest, dass das Skript simpleWeather nach jQuery geladen werden soll und dass jQuery unter einer global verfügbaren Variable jQuery verfügbar sein soll, die das jQuery-Plug-In simpleWeather benötigt, um sich selbst zu registrieren.

Hinweis

Beachten Sie, dass der Eintrag zum Registrieren von jQuery jquery als namen der externen Ressource, aber jQuery als globalen Variablennamen verwendet. Der Name der externen Ressource ist der Name, den Sie in den import Anweisungen im Code verwenden. Dies ist auch der Name, der mit TypeScript-Typdeklarationen übereinstimmen muss. Der globale Variablenname, der mithilfe der globalName -Eigenschaft angegeben wird, ist der Name, der anderen Skripts bekannt ist, z. B. Plug-Ins, die auf der Bibliothek basieren. Bei einigen Bibliotheken sind diese Namen möglicherweise identisch, aber sie sind nicht erforderlich, und Sie sollten sorgfältig überprüfen, ob Sie die richtigen Namen verwenden, um Probleme zu vermeiden.

Es ist schwierig, manuell zu bestimmen, ob das Skript, das Sie laden möchten, ein Modul oder ein Nicht-Modulskript ist. Dies ist insbesondere dann der Fall, wenn das Skript minimiert ist. Wenn das Skript auf einer öffentlich zugänglichen URL gehostet wird, können Sie das kostenlose Tool Rencore SharePoint Framework Script Check verwenden, um die Art des Skripts zu ermitteln. Dieses Tool teilt Ihnen außerdem mit, ob der Hostingspeicherort, vom dem aus Sie das Skript laden, korrekt konfiguriert ist.

Zu bedenkende Aspekte bei Nicht-Modul-Skripts

Viele JavaScript-Bibliotheken und -Skripts, die in der Vergangenheit entwickelt wurden, werden als Nicht-Modul-Skripts verteilt. Das SharePoint Framework unterstützt zwar das Laden von Nicht-Modul-Skripts, Sie sollten von deren Verwendung aber dennoch wann immer möglich absehen.

Nicht-Modulskripts werden im globalen Bereich der Seite registriert: Ein skript, das von einem Webpart geladen wird, ist für alle anderen Webparts auf der Seite verfügbar. Wenn Sie zwei Webparts mit unterschiedlichen Versionen von jQuery hatten, die beide als Nicht-Modulskripts geladen wurden, würde das Webpart, das das letzte geladen hat, alle zuvor registrierten Versionen von jQuery überschrieben.

Wie Sie sich vorstellen können, könnte das zu unvorhersehbaren Ergebnissen und Problemen führen, die sich nur schwer debuggen lassen und die nur in bestimmten Szenarien auftreten würden: beispielsweise nur, wenn auf der Seite andere Webparts eingesetzt werden, die eine andere jQuery-Version verwenden, und nur, wenn diese Webparts in einer bestimmten Reihenfolge geladen werden. Die Modularchitektur löst dieses Problem durch Isolierung der Skripts. Das verhindert, dass sie sich gegenseitig beeinflussen.

Wann Bundling sinnvoll ist

Das Bündeln vorhandener JavaScript-Bibliotheken in Ihrem Webpart kann zu großen Webpartdateien führen und zu einer schlechten Leistung von Seiten führen, die dieses Webpart verwenden. Obwohl Sie im Allgemeinen vermeiden sollten, JavaScript-Bibliotheken mit Ihren Webparts zu bündeln, gibt es Szenarien, in denen die Bündelung zu Ihrem Vorteil funktionieren könnte.

Wenn Sie eine Standardlösung erstellen, die in jedem Intranet funktionieren soll, kann das Bundling aller Ressourcen mit Ihrem Webpart sicherstellen, dass Ihr Webpart wie erwartet funktioniert. Schließlich wissen Sie vorab nicht, wo Ihre Lösung installiert werden wird. Wenn alle Abhängigkeiten in der Bundledatei Ihres Webparts enthalten sind, kann es ordnungsgemäß arbeiten, auch dann, wenn eine Organisation Ressourcendownloads aus CDNs oder von anderen externen Speicherorten nicht erlaubt.

Wenn Ihre Lösung aus vielen Webparts besteht, die alle eine bestimmte Funktionalität nutzen, wäre es besser, diese gemeinsam genutzte Funktionalität als separate Bibliothek zu erstellen und in allen Webparts als externe Ressource zu referenzieren. Benutzer müssten die gemeinsam genutzte Bibliothek dann nur ein einziges Mal herunterladen und könnten sie mit allen Webparts wiederverwenden.

Zusammenfassung

Bei der Erstellung clientseitiger Webparts im SharePoint-Framework können Sie bereits vorhandene JavaScript-Bibliotheken nutzen, um leistungsstarke Lösungen zu programmieren. Das SharePoint-Framework lässt Ihnen die Wahl, ob Sie diese Bibliotheken mit Ihren Webparts in einem Bundle zusammenfassen oder als externe Ressourcen laden. Die allgemein empfohlene Strategie ist es, vorhandene Bibliotheken von einer URL zu laden. In manchen Szenarien hat aber auch Bundling Vorteile. Es ist daher essenziell, dass Sie Ihre Anforderungen sorgfältig analysieren und den Ansatz wählen, der diese Anforderungen am besten erfüllt.

Weitere Artikel

• SharePoint Framework-Übersicht