Hinzufügen einer externen Bibliothek zu Ihrem clientseitigen SharePoint-WebpartAdd an external library to your SharePoint client-side web part

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.You might want to include one or more JavaScript libraries in your web part. This article shows you how to bundle an external library and share libraries.

Bündeln eines SkriptsBundle a script

Der Webpart-Bundler schließt standardmäßig automatisch jede Bibliothek ein, die eine Abhängigkeit des Webpartmoduls aufweist.By default, the web part bundler automatically includes any library that is a dependency of the web part module. Dies bedeutet, dass die Bibliothek in derselben JavaScript-Bundledatei wie Ihr Webpart bereitgestellt wird.This means that the library is deployed in the same JavaScript bundle file as your web part. Dies ist bei kleineren Bibliotheken hilfreich, die nicht in mehreren Webparts verwendet werden.This is more useful for smaller libraries that are not used in multiple web parts.

BeispielExample

  1. Schließen Sie die Zeichenfolge, die das validator-Paket der Bibliothek überprüft, in ein Webpart ein.Include the string validating library validator package into a web part.

  2. Laden Sie das validator-Paket von npm herunter:Download the validator package from npm:

    npm install validator --save
    

    Hinweis

    Da Sie TypeScript verwenden, benötigen Sie für das Paket, das Sie hinzufügen, Eingaben. Dies ist wichtig, 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 mithilfe von npm nach Eingaben suchen, beispielsweise: npm install @types/{package} --save-devBecause you're using TypeScript, you need typings for the package you add. This is essential when you are writing code because TypeScript is just a superset of JavaScript. All the TypeScript code is still converted to JavaScript code when you compile. You can search for and find typings by using npm, for example: 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 den nachfolgenden Code in die Datei ein:Create a file in the your web part's folder called validator.d.ts and add the following:

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

    Hinweis

    Manche Bibliotheken verfügen nicht über Eingaben.Some libraries do not have typings. Die validator-Bibliothek verfügt zwar über eine von der Community bereitgestellte Eingabendatei, in diesem Szenario wird aber davon ausgegangen, dass dies nicht der Fall ist.While the validator library does have a community provided typings file, for this scenario let's assume it does not. In diesem Fall müssen Sie Ihre eigene .d.ts-Datei für die Eingabedefinition für die Bibliothek definieren.In this case, you would want to define your own typings definition .d.ts file for the library. Im vorherigen Code ist ein Beispiel dargestellt:The previous code shows an example.

  4. Importieren Sie die Eingaben in Ihre Webpartdatei:In your web part file, import the typings:

    import * as validator from 'validator';
    
  5. Verwenden Sie die validator-Bibliothek im Webpartcode:Use the validator library in your web part code:

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

Freigeben einer Bibliothek zwischen mehreren WebpartsShare a library among multiple web parts

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.Your client-side solution might include multiple web parts. These web parts might need to import or share the same library. In such cases, instead of bundling the library, you should include it in a separate JavaScript file to improve performance and caching. This is especially true of larger libraries.

BeispielExample

In diesem Beispiel geben Sie das marked-Paket - einen Markdown-Compiler - in einem separaten Bundle frei.In this example, you will share the marked package (a markdown compiler) in a separate bundle.

  1. Herunterladen des marked-Pakets von npm:Download the marked package from npm:

    npm install marked --save
    
  2. Herunterladen der Eingaben:Download the typings:

    npm install @types/marked --save-dev
    
  3. Bearbeiten Sie config/config.json, und fügen Sie einen Eintrag zur Zuordnung externals hinzu.Edit the config/config.json, and add an entry to the externals map. Dadurch wird dem Bundler mitgeteilt, dies in einer separaten Datei zu platzieren.This is what tells the bundler to put this in a separate file. Dadurch wird verhindert, dass der Bundler diese Bibliothek bündelt:This prevents the bundler from bundling this library:

    "marked": "node_modules/marked/marked.min.js"
    
  4. Fügen Sie die Anweisung zum Importieren der marked-Bibliothek nun in das Webpart ein, nachdem Sie das Paket und die Eingaben für die Bibliothek hinzugefügt haben:Add the statement to import the marked library in your web part now that we have added the package and typings for the library:

    import * as marked from 'marked';
    
  5. Verwenden der Bibliothek im Webpart:Use the library in your web part:

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

Laden eines Skripts aus einem CDNLoad a script from a CDN

Anstatt die Bibliothek aus einem npm-Paket zu laden, können Sie ein Skript aus einem Content Delivery Network (CDN) laden.Instead of loading the library from an npm package, you might want to load a script from a Content Delivery Network (CDN). Bearbeiten Sie hierzu die config.json-Datei, um die Bibliothek von ihrer CDN-URL zu laden.To do so, edit the config.json file to load the library from its CDN URL.

BeispielExample

In diesem Beispiel laden Sie jQuery aus einem CDN. Sie müssen nicht das npm-Paket installieren. Sie müssen jedoch die Eingaben installieren.In this example, you will load jQuery from CDN. You don't need to install the npm package. However, you still need to install the typings.

  1. Installieren der Eingaben für jQuery:Install the typings for jQuery:

    npm install --save-dev @types/jquery
    
  2. Aktualisieren Sie config.json im Ordner config, um jQuery aus einem CDN zu laden. Hinzufügen eines Eintrags zum externals-Feld:Update the config.json in the config folder to load jQuery from CDN. Add an entry to the externals field:

    "jquery": "https://code.jquery.com/jquery-3.1.0.min.js"
    
  3. Importieren von jQuery in das Webpart:Import jQuery in your web part:

    import * as $ from 'jquery';
    
  4. Verwenden von jQuery im Webpart:Use jQuery in your web part:

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

Laden eines Nicht-AMD-ModulsLoad a non-AMD module

Einige Skripts folgen dem veralteten JavaScript-Muster des Speicherns der Bibliothek im globalen Namespace. Dieses Muster wurde nun durch Universal Modul Definitions (UMD), / Asynchronous Module Definitions (AMD) oder ES6-Module ersetzt. Möglicherweise müssen Sie solche Bibliotheken jedoch in das Webpart laden.Some scripts follow the legacy JavaScript pattern of storing the library on the global namespace. This pattern is now deprecated in favor of Universal Module Definitions (UMD) / Asynchronous Module Definitions (AMD) or ES6 modules. However, you might need to load such libraries in your web part.

Tipp

Es ist schwierig, manuell ermitteln, ob das Skript, das Sie laden möchten, ein AMD- oder ein Nicht-AMD-Skript ist.It's difficult to determine manually whether the script that you're trying to load is an AMD or a non-AMD script. Dies ist insbesondere dann der Fall, wenn das Skript minimiert ist.This is especially the case if the script that you're trying to load is minified. 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.If your script is hosted on a publicly accessible URL, you can use the free Rencore SharePoint Framework Script Check tool to determine the type of script for you. Dieses Tool teilt Ihnen außerdem mit, ob der Hostingspeicherort, vom dem aus Sie das Skript laden, korrekt konfiguriert ist.Additionally, this tool lets you know whether the hosting location from which you're loading the script is properly configured.

Um ein Nicht-AMD-Modul zu laden, fügen Sie eine zusätzliche Eigenschaft zu dem Eintrag in der config.json-Datei hinzu.To load a non-AMD module, you add an additional property to the entry in your config.json file.

BeispielExample

In diesem Beispiel laden Sie ein fiktives Nicht-AMD-Modul aus dem Contoso-CDN. Diese Schritte gelten für alle Nicht-AMD Skripts im Verzeichnis „src/“ oder „node_modules/“.In this example, you will load a fictional non-AMD module from Contoso's CDN. These steps apply for any non-AMD script in your src/ or node_modules/ directory.

Das Skript heißt Contoso.js und ist unter https://contoso.com/contoso.js gespeichert. Es hat folgenden Inhalt:The script is called Contoso.js and is stored at https://contoso.com/contoso.js. Its contents are:

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

  1. Erstellen von Eingaben für das Skript in einer Datei mit dem Namen contoso.d.ts im Webpartordner.Create typings for the script in a file called contoso.d.ts in the web part folder.

    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:Update the config.json file to include this script. Add an entry to the externals map:

    {
        "contoso": {
            "path": "https://contoso.com/contoso.js",
            "globalName": "ContosoJS"
        }
    }
    
  3. Hinzufügen eines Imports zum Webpartcode:Add an import to your web part code:

    import contoso from 'contoso';
    
  4. Verwenden der Contoso-Bibliothek im Code:Use the contoso library in your code:

    contoso.sayHello(username);
    

Laden einer Bibliothek, die eine Abhängigkeit von einer anderen Bibliothek aufweistLoad a library that has a dependency on another library

Viele Bibliotheken weisen Abhängigkeiten von einer anderen Bibliothek auf.Many libraries have dependencies on another library. Sie können solche Abhängigkeiten in der config.json-Datei mithilfe der globalDependencies-Eigenschaft angeben.You can specify such dependencies in the config.json file by using the globalDependencies property.

Wichtig

Beachten Sie, dass Sie dieses Feld für AMD-Module nicht angeben müssen; diese importieren sich gegenseitig ordnungsgemäß.Note that you don't have to specify this field for AMD modules; they properly import each other. Ein Nicht-AMD-Modul kann jedoch kein AMD-Modul als Abhängigkeit aufweisen.However, a non-AMD module cannot have an AMD module as a dependency. In einigen Fällen ist es möglich, ein AMD-Skript als Nicht-AMD-Skript zu laden.In some cases, it is possible to load an AMD script as a non-AMD script. 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.This is often required when working with jQuery, which by itself is an AMD script, and jQuery plug-ins, which most of the time are distributed as non-AMD scripts and which depend on jQuery.

Hierfür gibt es zwei Beispiele.There are two examples of this.

Nicht-AMD-Modul weist eine Abhängigkeit zu einem Nicht-AMD-Modul aufNon-AMD module has a non-AMD module dependency

In diesem Beispiel gibt es zwei fiktive Skripts. Sie befinden sich im Ordner src/, können jedoch auch aus einem CDN geladen werden.This example involves two fictional scripts. These are in the src/ folder, although they can also be loaded from a CDN.

ContosoUI.jsContosoUI.js

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

ContosoCore.jsContosoCore.js

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

  1. Fügen Sie Eingaben für diese Klasse hinzu, oder erstellen Sie sie. In diesem Fall erstellen Sie Contoso.d.ts mit Eingaben für beide JavaScript-Dateien.Add or create typings for this class. In this case, you will create Contoso.d.ts, which contains typings for both JavaScript files.

    contoso.d.tscontoso.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. Hinzufügen von zwei Einträgen zu externals:Update the config.json file. Add two entries to 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:Add imports for Contoso and ContosoUI:

    import contoso = require('contoso');
    require('contoso-ui');
    
  4. Verwenden der Bibliotheken im Code:Use the libraries in your code:

    contoso.EventList.alert();
    

Laden von SharePoint JSOMLoad SharePoint JSOM

Das Laden von SharePoint JSOM ist im Wesentlichen das gleiche Szenario wie das Laden von Nicht-AMD-Skripts, die Abhängigkeiten haben. Hierfür wird sowohl die Option globalName als auch die Option globalDependency verwendet.Loading SharePoint JSOM is essentially the same scenario as loading non-AMD scripts that have dependencies. This means using both the globalName and globalDependency options.

Wichtig

Beachten Sie, dass der folgende Ansatz auf klassischen SharePoint-Seiten Fehler verursacht, auf denen SharePoint JSOM bereits geladen ist.Note that the following approach causes errors in classic SharePoint pages, where SharePoint JSOM is already loaded. 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.If you require your web part to work with both classic and modern pages, you should first check if SharePoint JSOM is already available, and if it isn't, load it dynamically by using the SPComponentLoader.


  1. Installieren von Eingaben für Microsoft Ajax (Abhängigkeit für JSOM-Eingaben):Install typings for Microsoft Ajax, which is a dependency for JSOM typings:

    npm install @types/microsoft-ajax --save-dev
    
  2. Installieren von Eingaben für JSOM:Install typings for the JSOM:

    npm install @types/sharepoint --save-dev
    
  3. Hinzufügen von Einträgen zu config.json:Add entries to the 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 require-Anweisungen hinzu:In your web part, add the require statements:

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

Laden lokalisierter RessourcenLoad localized resources

Sie können eine Zuordnung in config.json mit dem Namen localizedResources verwenden, um zu beschreiben, wie lokalisierte Ressourcen geladen werden.You can use a map in config.json called localizedResources to describe how to load localized resources. Pfade in dieser Zuordnung sind relativ zum lib-Ordner und dürfen keinen vorangestellten Schrägstrich (/) enthalten.Paths in this map are relative to the lib folder and must not contain a leading slash (/).

In diesem Beispiel haben Sie den Ordner src/strings/. In diesem Ordner befinden sich 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:In this example, you have a folder src/strings/. In this folder are several JavaScript files with names such as en-us.js, fr-fr.js, de-de.js. Because each of these files must be loadable by the module loader, they must contain a CommonJS wrapper. For example, in en-us.js:

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

  1. Bearbeiten Sie die config.json-Datei.Edit the config.json file. Fügen Sie einen Eintrag zu localizedResources hinzu.Add an entry to localizedResources. {locale} ist ein Platzhaltertoken für den Gebietsschemanamen:{locale} is a placeholder token for the locale name:

    {
        "strings": "strings/{locale}.js"
    }
    
  2. Fügen Sie Eingaben für Ihre Zeichenfolgen hinzu. In diesem Fall haben Sie die Datei MyStrings.d.ts:Add typings for your strings. In this case, you have a file 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:Add imports for the strings in your project:

    import * as strings from 'mystrings';
    
  4. Verwenden der Zeichenfolgen in Ihrem Projekt:Use the strings in your project:

    alert(strings.initialPrompt);
    

Weitere ArtikelSee also