Hinzufügen einer externen Bibliothek zu Ihrem clientseitigen SharePoint-Webpart

  • Artikel

Vielleicht möchten Sie eine oder mehrere JavaScript-Bibliotheken in Ihr Webpart einfügen. In diesem Artikel wird gezeigt, wie Sie eine externe Bibliothek bündeln und Bibliotheken freigeben.

Bündeln eines Skripts

Der Webpart-Bundler schließt standardmäßig automatisch jede Bibliothek ein, die eine Abhängigkeit des Webpartmoduls aufweist. Dies bedeutet, dass die Bibliothek in derselben JavaScript-Bundledatei wie Ihr Webpart bereitgestellt wird. Dies ist bei kleineren Bibliotheken hilfreich, die nicht in mehreren Webparts verwendet werden.

Beispiel

  1. Schließen Sie die Zeichenfolge, die das validator-Paket der Bibliothek überprüft, in ein Webpart ein.

  2. Laden Sie das validator-Paket von NPM herunter:

    npm install validator --save

    Hinweis

    Da Sie TypeScript verwenden, benötigen Sie wahrscheinlich die Typdeklarationen für das Paket, das Sie hinzufügen. Dies ist nützlich, wenn Sie Code schreiben, da TypeScript nur eine Obermenge von JavaScript ist. Der gesamte TypeScript-Code wird beim Kompilieren nach wie vor in JavaScript-Code konvertiert. Sie können Typdeklarationen mithilfe von NPM installieren, z. B.: npm install @types/{package} --save-dev

  3. Erstellen Sie im Ordner Ihres Webparts eine Datei mit dem Namen validator.d.ts, und fügen Sie Folgendes ein:

    declare module "validator" {
    export function isEmail(email: string): boolean;
    export function isAscii(text: string): boolean;
}

    Hinweis

    Manche Bibliotheken verfügen nicht über Typdeklarationen. Die validator-Bibliothek verfügt zwar über eine von der Community bereitgestellte Typdeklarationsdatei, in diesem Szenario wird aber davon ausgegangen, dass dies nicht der Fall ist. In diesem Fall müssen Sie Ihre eigene .d.ts-Datei für die Typdeklarationen für die Bibliothek definieren. Im vorherigen Code ist ein Beispiel dargestellt:

  4. Importieren Sie die Typdeklarationen in Ihre Webpartdatei:

    import * as validator from 'validator';

  5. Verwenden Sie die validator-Bibliothek im Webpartcode:

    validator.isEmail('someone@example.com');

Freigeben einer Bibliothek zwischen mehreren Webparts

Ihre clientseitige Lösung umfasst möglicherweise mehrere Webparts. Diese Webparts müssen möglicherweise die gleiche Bibliothek importieren oder freigeben. In solchen Fällen sollten Sie die Bibliothek in eine separate JavaScript-Datei einschließen, anstatt sie zu bündeln, um Leistung und Zwischenspeicherung zu verbessern. Dies gilt besonders für größere Bibliotheken.

Beispiel

In diesem Beispiel geben Sie das marked-Paket (einen Markdown-Compiler) in einem separaten Bundle frei.

  1. Laden Sie das marked-Paket von NPM herunter:

    npm install marked --save

  2. Installieren Sie das Typdeklarationenpaket in Ihrem Projekt:

    npm install @types/marked --save-dev

  3. Bearbeiten Sie config/config.json, und fügen Sie einen Eintrag zur Zuordnung externals hinzu. Dadurch wird dem Bundler mitgeteilt, dies in einer separaten Datei zu platzieren. Dadurch wird verhindert, dass der Bundler diese Bibliothek bündelt:

    "marked": "node_modules/marked/marked.min.js"

  4. Fügen Sie die Anweisung zum Importieren der marked-Bibliothek nun dem Webpart hinzu, nachdem Sie das Paket und die Typdeklarationen für die Bibliothek hinzugefügt haben:

    import * as marked from 'marked';

  5. Verwenden der Bibliothek im Webpart:

    console.log(marked('I am using __markdown__.'));

Laden eines Skripts aus einem CDN

Anstatt die Bibliothek aus einem NPM-Paket zu laden, können Sie ein Skript aus einem Content Delivery Network (CDN) laden. Bearbeiten Sie hierzu die config.json-Datei, um die Bibliothek von ihrer CDN-URL zu laden.

Beispiel

In diesem Beispiel laden Sie jQuery aus CDN. Sie müssen das NPM-Paket nicht installieren. Sie müssen jedoch weiterhin die Typdeklarationen installieren.

  1. Installieren Sie die Typdeklarationen für jQuery:

    npm install --save-dev @types/jquery

  2. Aktualisieren Sie config.json im Ordner config , um jQuery aus CDN zu laden. Hinzufügen eines Eintrags zum externals-Feld:

    "jquery": "https://code.jquery.com/jquery-3.1.0.min.js"

  3. Importieren von jQuery in das Webpart:

    import * as $ from 'jquery';

  4. Verwenden von jQuery im Webpart:

    alert( $('#foo').val() );

Laden eines Nicht-AMD-Moduls

Einige Skripts folgen dem Legacy-JavaScript-Muster zum Speichern der Bibliothek im globalen Namespace. Dieses Muster ist jetzt zugunsten von UMD-Modulen (Universal Module Definitions),/asynchronen Moduldefinitionen (AMD) oder ES6-Modulen veraltet. Möglicherweise müssen Sie solche Bibliotheken jedoch in Ihr Webpart laden.

Tipp

Es ist schwierig, manuell ermitteln, ob das Skript, das Sie laden möchten, ein AMD- oder ein Nicht-AMD-Skript 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. Dieses Tool ist auch in der VS-Code-Erweiterung Rencore SPFx Script Check verfügbar.

Um ein Nicht-AMD-Modul zu laden, fügen Sie eine zusätzliche Eigenschaft zu dem Eintrag in der config.json-Datei hinzu.

Beispiel

In diesem Beispiel laden Sie ein fiktives Nicht-AMD-Modul aus dem CDN von Contoso. Diese Schritte gelten für alle Nicht-AMD-Skripts in Ihrem src/- oder node_modules/-Verzeichnis.

Das Skript heißt Contoso.js und ist unter https://contoso.com/contoso.js gespeichert. Sein Inhalt ist wie folgt:

var ContosoJS = {
  say: function(text) { alert(text); },
  sayHello: function(name) { alert('Hello, ' + name + '!'); }
};

  1. Erstellen Sie Typdeklarationen für das Skript in einer Datei mit dem Namen contoso.d.ts im Webpartordner.

    declare module "contoso" {
  interface IContoso {
    say(text: string): void;
    sayHello(name: string): void;
  }
  var contoso: IContoso;
  export = contoso;
}

  2. Aktualisieren der config.json-Datei derart, dass dieses Skript eingeschlossen wird. Hinzufügen eines Eintrags zur externals-Zuordnung:

    {
  "contoso": {
    "path": "https://contoso.com/contoso.js",
    "globalName": "ContosoJS"
  }
}

  3. Hinzufügen eines Imports zum Webpartcode:

    import contoso from 'contoso';

  4. Verwenden der Contoso-Bibliothek im Code:

    contoso.sayHello(username);

Laden einer Bibliothek, die eine Abhängigkeit von einer anderen Bibliothek aufweist

Viele Bibliotheken weisen Abhängigkeiten von einer anderen Bibliothek auf. Sie können solche Abhängigkeiten in der config.json-Datei mithilfe der globalDependencies-Eigenschaft angeben.

Wichtig

Beachten Sie, dass Sie dieses Feld für AMD-Module nicht angeben müssen; diese importieren sich gegenseitig ordnungsgemäß. Ein Nicht-AMD-Modul kann jedoch kein AMD-Modul als Abhängigkeit aufweisen. In einigen Fällen ist es möglich, ein AMD-Skript als Nicht-AMD-Skript zu laden. Dies ist häufig bei der Arbeit mit jQuery (selbst ein AMD-Skript) und jQuery-Plug-Ins erforderlich, die meistens als Nicht-AMD-Skripts verteilt werden und von jQuery abhängig sind.

Hierfür gibt es zwei Beispiele.

Nicht-AMD-Modul weist eine Abhängigkeit zu einem Nicht-AMD-Modul auf

In diesem Beispiel gibt es zwei fiktive Skripts. Sie befinden sich im Ordner src/, können jedoch auch aus einem CDN geladen werden.

ContosoUI.js

Contoso.EventList = {
  alert: function() {
    var events = Contoso.getEvents();
    events.forEach( function(event) {
      alert(event);
    });
  }
}

ContosoCore.js

var Contoso = {
  getEvents: function() {
    return ['A', 'B', 'C'];
  }
};

  1. Fügen Sie Typdeklarationen für diese Klasse hinzu, oder erstellen Sie sie. In diesem Fall erstellen Sie Contoso.d.ts, das Typdeklarationen für beide JavaScript-Dateien enthält.

    contoso.d.ts

    declare module "contoso" {
  interface IEventList {
    alert(): void;
  }
  interface IContoso {
    getEvents(): string[];
    EventList: IEventList;
  }
  var contoso: IContoso;
  export = contoso;
}

  2. Aktualisieren Sie die config.json-Datei. Fügen Sie zwei Einträge zu hinzu externals:

    {
  "contoso": {
    "path": "/src/ContosoCore.js",
    "globalName": "Contoso"
  },
  "contoso-ui": {
    "path": "/src/ContosoUI.js",
    "globalName": "Contoso",
    "globalDependencies": ["contoso"]
  }
}

  3. Hinzufügen von Importen für Contoso und ContosoUI:

    import contoso = require('contoso');
require('contoso-ui');

  4. Verwenden der Bibliotheken im Code:

    contoso.EventList.alert();

Laden von SharePoint JSOM

Das Laden von SharePoint JSOM ist im Wesentlichen das gleiche Szenario wie das Laden von Nicht-AMD-Skripts, die Abhängigkeiten haben. Dies bedeutet, dass sowohl die globalName Optionen als auch verwendet globalDependency werden.

Wichtig

Beachten Sie, dass der folgende Ansatz auf klassischen SharePoint-Seiten Fehler verursacht, auf denen SharePoint JSOM bereits geladen ist. Wenn Ihr Webpart sowohl mit klassischen als auch mit modernen Seiten arbeiten soll, sollten Sie zuerst überprüfen, ob SharePoint JSOM bereits verfügbar ist. Ist dies nicht der fall, laden Sie es dynamisch mithilfe von SPComponentLoader.

  1. Installieren Sie Typdeklarationen für Microsoft Ajax (Abhängigkeit für JSOM-Typdeklarationen):

    npm install @types/microsoft-ajax --save-dev

  2. Installieren Sie Typdeklarationen für die JSOM:

    npm install @types/sharepoint --save-dev

  3. Hinzufügen von Einträgen zu config.json:

    {
  "sp-init": {
    "path": "https://CONTOSO.sharepoint.com/_layouts/15/init.js",
    "globalName": "$_global_init"
  },
  "microsoft-ajax": {
    "path": "https://CONTOSO.sharepoint.com/_layouts/15/MicrosoftAjax.js",
    "globalName": "Sys",
    "globalDependencies": [ "sp-init" ]
  },
  "sp-runtime": {
    "path": "https://CONTOSO.sharepoint.com/_layouts/15/SP.Runtime.js",
    "globalName": "SP",
    "globalDependencies": [ "microsoft-ajax" ]
  },
  "sharepoint": {
    "path": "https://CONTOSO.sharepoint.com/_layouts/15/SP.js",
    "globalName": "SP",
    "globalDependencies": [ "sp-runtime" ]
  }
}

  4. Fügen Sie in Ihrem Webpart die folgenden require-Anweisungen hinzu:

    require('sp-init');
require('microsoft-ajax');
require('sp-runtime');
require('sharepoint');

Laden lokalisierter Ressourcen

Sie können eine Zuordnung in config.json mit dem Namen localizedResources verwenden, um zu beschreiben, wie lokalisierte Ressourcen geladen werden sollen. Pfade in dieser Zuordnung sind relativ zum lib-Ordner und dürfen keinen vorangestellten Schrägstrich (/) enthalten.

In diesem Beispiel haben Sie den Ordner src/strings/. In diesem Ordner gibt es mehrere JavaScript-Dateien mit Namen wie en-us.js, fr-fr.js ,de-de.js. Da jede dieser Dateien vom Modulladeprogramm geladen werden muss, müssen sie einen CommonJS-Wrapper enthalten. In en-us.js beispielsweise:

  define([], function() {
    return {
      "PropertyPaneDescription": "Description",
      "BasicGroupName": "Group Name",
      "DescriptionFieldLabel": "Description Field"
    }
  });

  1. Bearbeiten Sie die config.json-Datei. Fügen Sie einen Eintrag zu localizedResources hinzu. {locale} ist ein Platzhaltertoken für den Gebietsschemanamen:

    {
  "strings": "strings/{locale}.js"
}

  2. Fügen Sie Typdeklarationen für Ihre Zeichenfolgen hinzu. In diesem Fall haben Sie die Datei MyStrings.d.ts:

    declare interface IStrings {
  webpartTitle: string;
  initialPrompt: string;
  exitPrompt: string;
}

declare module 'mystrings' {
  const strings: IStrings;
  export = strings;
}

  3. Hinzufügen von Importen für die Zeichenfolgen in Ihrem Projekt:

    import * as strings from 'mystrings';

  4. Verwenden der Zeichenfolgen in Ihrem Projekt:

    alert(strings.initialPrompt);

Weitere Artikel