Добавление внешней библиотеки в клиентскую веб-часть SharePoint

Статья
03/21/2023

Вам может понадобиться добавить в веб-часть одну или несколько библиотек JavaScript. В этой статье описано, как добавить внешнюю библиотеку в пакет и использовать библиотеки в нескольких веб-частях.

Добавление сценария в пакет

По умолчанию средство увязки веб-частей в пакеты автоматически добавляет библиотеки, которые представляют собой зависимости для модуля веб-части. Это означает, что такие библиотеки развертываются в том же файле пакета JavaScript, что и веб-часть. Это удобно в случае небольших библиотек, которые не используются в нескольких веб-частях.

Пример

Добавьте библиотеку проверки строк в веб-часть.
Скачайте пакет средств проверки, используя NPM:
```
npm install validator --save
```
Примечание.

Так как вы используете TypeScript, скорее всего, вам понадобятся объявления типов для добавляемого пакета. Это полезно при написании кода, так как TypeScript — это просто надмножество JavaScript. Весь код TypeScript по-прежнему преобразуется в код JavaScript при компиляции. Объявления типов можно установить с помощью NPM, например npm install @types/{package} --save-dev.
Создайте в папке веб-части файл с именем validator.d.ts и добавьте следующее:
```
declare module "validator" {
    export function isEmail(email: string): boolean;
    export function isAscii(text: string): boolean;
}
```
Примечание.

Для некоторых библиотек нет объявлений типов. Хотя в библиотеке проверки имеется созданный сообществом файл объявлений типов, но для этого сценария предположим, что его нет. В этом случае нужно задать собственный файл определений объявлений типов .d.ts для библиотеки. Ниже приведен пример.
Импортируйте объявления типов в файле веб-части:
```
import * as validator from 'validator';
```
Укажите библиотеку проверки в коде веб-части:
```
validator.isEmail('someone@example.com');
```

Клиентское решение может включать несколько веб-частей. Для них может потребоваться импортировать или использовать одну и ту же библиотеку. В таких случаях не добавляйте библиотеку в пакет, а включите ее в отдельный файл JavaScript, чтобы повысить эффективность и улучшить кэширование. Особенно это касается больших библиотек.

Пример

В этом примере пакет marked (компилятор markdown) помещается в отдельный пакет для совместного использования.

Скачайте пакет marked с помощью NPM:
```
npm install marked --save
```
Установите пакет объявлений типов в свой проект:
```
npm install @types/marked --save-dev
```
Измените config/config.json и добавьте запись в схему externals. В результате средство увязки поместит эту библиотеку в отдельный файл, а не добавит в пакет:
```
"marked": "node_modules/marked/marked.min.js"
```
Теперь, когда мы добавили пакет и объявления типов для библиотеки, добавьте оператор для импорта библиотеки marked в веб-части:
```
import * as marked from 'marked';
```
Укажите библиотеку в своей веб-части:
```
console.log(marked('I am using __markdown__.'));
```

Загрузка сценария из сети CDN

Вы можете не загружать библиотеку из пакета NPM, а загрузить сценарий из сети доставки содержимого (CDN). Для этого измените файл config.json, чтобы обеспечить загрузку библиотеки с использованием URL-адреса CDN.

Пример

В этом примере вы загрузите jQuery из CDN. Вам не нужно устанавливать пакет NPM. Однако по-прежнему необходимо установить объявления типов.

Установка объявлений типов для jQuery:
```
npm install --save-dev @types/jquery
```
Обновите файл config.json в папке config , чтобы загрузить jQuery из CDN. Добавьте запись в поле externals:
```
"jquery": "https://code.jquery.com/jquery-3.1.0.min.js"
```
Импортируйте jQuery в веб-часть:
```
import * as $ from 'jquery';
```
Используйте jQuery в своей веб-части:
```
alert( $('#foo').val() );
```

Загрузка модуля, отличного от AMD-модуля

Некоторые скрипты следуют устаревшей схеме JavaScript хранения библиотеки в глобальном пространстве имен. Этот шаблон теперь не рекомендуется использовать в пользу универсальных определений модулей (UMD)/асинхронных определений модулей (AMD) или модулей ES6. Однако может потребоваться загрузить такие библиотеки в веб-части.

Совет

Трудно определить вручную, является ли загружаемый сценарий сценарием AMD, особенно если он минифицирован.

Если ваш сценарий размещен по общедоступному URL-адресу, вы можете использовать бесплатный инструмент Rencore SharePoint Framework Script Check, чтобы автоматически определить тип сценария. Кроме того, этот инструмент позволяет узнать, правильно ли настроен место размещения, с которого загружается сценарий. Этот инструмент также доступен в расширении VS Code Rencore SPFx Script Check

Чтобы загрузить модуль, созданный не с помощью AMD, добавьте дополнительное свойство в запись в файле config.json.

Пример

В этом примере вы загрузите вымышленный модуль, отличный от AMD, из сети CDN Компании Contoso. Эти действия применяются для любого сценария, отличного от AMD, в каталоге src/ или node_modules/.

Скрипт называется Contoso.js и хранится в https://contoso.com/contoso.js. Его содержимое:

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

Создайте объявления типов для сценария в файле contoso.d.ts в папке веб-части.

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

Включите этот сценарий в файл config.json. Добавьте запись в схему externals:
```
{
  "contoso": {
    "path": "https://contoso.com/contoso.js",
    "globalName": "ContosoJS"
  }
}
```
Добавьте операцию импорта в код веб-части:
```
import contoso from 'contoso';
```
Используйте библиотеку contoso в своем коде:
```
contoso.sayHello(username);
```

Загрузка библиотеки с зависимостью от другой библиотеки

Многие библиотеки содержат зависимости от другой библиотеки. Такие зависимости можно указать в файле config.json с помощью свойства globalDependencies.

Важно!

Обратите внимание, что это поле не нужно указывать для AMD-модулей. Они импортируют друг друга правильно. Однако AMD-модуль не может зависеть от модуля, отличного от AMD. В некоторых случаях можно загрузить сценарий AMD в виде сценария, отличного от AMD. Это часто требуется при работе с библиотекой jQuery, которая сама по себе является сценарием AMD, и подключаемыми модулями jQuery, которые в большинстве случаев распространяются как сценарии, отличные от AMD, и зависят от jQuery.

Ниже приведены два примера.

Для модуля, отличного от AMD-модуля, предусмотрена соответствующая зависимость

В этом примере используются два вымышленных сценария. Они хранятся в папке src/, но их также можно загрузить из CDN.

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'];
  }
};

Добавление или создание объявлений типов для этого класса. В этом случае вы создадите Contoso.d.ts, который содержит объявления типов для обоих файлов JavaScript.

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

Обновите файл config.json. Добавьте две записи в externals:

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

Добавьте операции импорта для Contoso и ContosoUI:
```
import contoso = require('contoso');
require('contoso-ui');
```
Укажите библиотеки в своем коде:
```
contoso.EventList.alert();
```

Загрузка JSOM SharePoint

Модели JSOM SharePoint загружаются практически так же, как сценарии с зависимостями, отличные от AMD-сценариев. Это означает использование globalName параметров и globalDependency .

Важно!

Обратите внимание, что приведенный ниже подход вызовет ошибки на классических страницах SharePoint, где модель JSOM уже загружена. Если ваша веб-часть должна работать как с классическими, так и современными страницами, нужно сначала проверить, доступна ли модель JSOM, а если нет, загрузить ее динамически с помощью SPComponentLoader.

Установите объявления типов для Microsoft Ajax, которые являются зависимостью для объявлений типов JSOM:
```
npm install @types/microsoft-ajax --save-dev
```
Установите объявления типов для JSOM:
```
npm install @types/sharepoint --save-dev
```

Добавьте записи в файл 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" ]
  }
}

Добавьте в веб-часть следующие операторы require:

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

Загрузка локализованных ресурсов

В файле config.json вы можете использовать схему localizedResources, чтобы описать принцип загрузки локализованных ресурсов. Пути в этой схеме заданы относительно папки lib и не должны содержать начальную косую черту (/).

В этом примере у вас есть папка src/strings/. В этой папке есть несколько файлов JavaScript с такими именами, как en-us.js, fr-fr.js ,de-de.js. Так как каждый из этих файлов должен загружаться загрузчиком модулей, они должны содержать оберточный код CommonJS. Например, в случае файла en-us.js:

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

Измените файл config.json. Добавьте запись в localizedResources. {locale} — это замещающий токен для имени языкового стандарта.
```
{
  "strings": "strings/{locale}.js"
}
```

Добавьте объявления типов для строк. В этом случае у вас есть файл MyStrings.d.ts:

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

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

Добавьте операции импорта для строк в проекте:
```
import * as strings from 'mystrings';
```
Используйте строки в своем проекте:
```
alert(strings.initialPrompt);
```

См. также

Обзор SharePoint Framework

Поделиться через

Добавление внешней библиотеки в клиентскую веб-часть SharePoint

Добавление сценария в пакет

Пример

Пример

Загрузка сценария из сети CDN

Пример

Загрузка модуля, отличного от AMD-модуля

Пример

Загрузка библиотеки с зависимостью от другой библиотеки

Для модуля, отличного от AMD-модуля, предусмотрена соответствующая зависимость

Загрузка JSOM SharePoint

Загрузка локализованных ресурсов

См. также

Дополнительные ресурсы

Поделиться через

Добавление внешней библиотеки в клиентскую веб-часть SharePoint

Добавление сценария в пакет

Пример

Использование библиотеки несколькими веб-частями

Пример

Загрузка сценария из сети CDN

Пример

Загрузка модуля, отличного от AMD-модуля

Пример

Загрузка библиотеки с зависимостью от другой библиотеки

Для модуля, отличного от AMD-модуля, предусмотрена соответствующая зависимость

Загрузка JSOM SharePoint

Загрузка локализованных ресурсов

См. также

Дополнительные ресурсы