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

Использование существующих библиотек JavaScript в клиентских веб-частях SharePoint Framework

Для создания клиентских веб-частей на платформе SharePoint Framework можно использовать существующие библиотеки JavaScript. Однако существует ряд факторов, которые следует учитывать, чтобы веб-части не снижали скорость загрузки страниц SharePoint, на которых они используются.

Ссылка на существующие библиотеки как на пакеты

Наиболее распространенный способ ссылки на существующие библиотеки JavaScript в клиентских веб-частях SharePoint Framework предполагает их установку в проекте в виде пакета.

  1. Например, чтобы использовать Angular в клиентской веб-части, сначала нужно установить его с помощью npm:

    npm install angular --save

  2. Чтобы использовать Angular с TypeScript, необходимо установить объявления типов с помощью npm:

    npm install @types/angular --save-dev

  3. Необходимо сослаться на Angular в веб-части с помощью оператора import:

    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
}

Объединение ресурсов веб-части в пакет

Платформа SharePoint Framework использует цепочку инструментов для сборки, основанную на инструментах с открытым кодом, таких как gulp и Webpack. При создании проектов SharePoint Framework эти инструменты для сборки автоматически объединяют все ресурсы, на которые ссылается веб-часть, в один файл JavaScript. Этот процесс называется объединением.

Командное окно с задачей gulp bundle рядом с папкой dist SharePoint Framework с выходными файлами

У объединения в пакет есть ряд преимуществ. Во-первых, все ресурсы, необходимые веб-части, доступны в одном файле JavaScript. Это упрощает развертывание, так как веб-часть состоит из одного файла, и в процессе развертывания невозможно пропустить зависимость.

Так как веб-часть использует разные ресурсы, важно, чтобы они загружались в правильном порядке. Пакет веб-части, созданный средством Webpack при сборке, автоматически управляет загрузкой разных ресурсов, в том числе сопоставляет зависимости между ними.

У объединения веб-частей также есть преимущества для пользователей: быстрее скачать один большой файл, чем несколько маленьких. Веб-часть быстрее загружается на странице.

Но объединение существующих библиотек JavaScript с клиентскими веб-частями SharePoint Framework не лишено недостатков.

При объединении существующих платформ JavaScript на базе SharePoint Framework в пакет включаются все сценарии, на которые ссылается веб-часть. Например, размер оптимизированного пакета веб-части с Angular — более 170 КБ.

Снимок экрана: папка развертывания на экране проводника с выделенным файлом JavaScript пакета Hello World.

Если вы добавите в проект еще одну веб-часть на Angular и выполните сборку проекта, то получите два пакета размером более 170 КБ — по одному для каждой веб-части.

Снимок экрана: папка развертывания на экране проводника с двумя выделенными файлами JavaScript пакета Hello World.

Если вы добавите эти веб-части на страницу, каждый пользователь скачает Angular несколько раз. Этот подход неэффективен и замедляет загрузку страницы.

Ссылка на существующие библиотеки как на внешние ресурсы

Предпочтительный способ использования существующих библиотек в клиентских веб-частях SharePoint Framework — сослаться на них как на внешние ресурсы. В этом случае в веб-часть будет включаться только URL-адрес сценария. При добавлении на страницу веб-часть автоматически попытается загрузить все необходимые ресурсы с указанного URL-адреса.

Ссылаться на существующие библиотеки JavaScript на платформе SharePoint Framework легко, и для этого не требуется изменять код. Так как библиотека загружается при запуске с указанного URL-адреса, ее не нужно устанавливать как пакет в проекте.

Например, чтобы сослаться на Angular как на внешний ресурс в клиентской веб-части, сначала установите объявления типов TypeScript с помощью npm:

npm install @types/angular --save-dev

В файле config/config.json добавьте следующую запись к свойству externals:

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

Весь файл config/config.json будет выглядеть примерно так:

{
  "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"
  }
}

Необходимо сослаться на Angular в веб-части:

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
}

Если вы выполните сборку проекта сейчас, размер созданного пакета составит всего 6 КБ.

Снимок экрана: проводник с изображением папки развертывания с выделенным файлом JavaScript Hello Word.

Если вы добавите в проект еще одну веб-часть на Angular и выполните сборку проекта, размер каждого пакета составит 6 КБ.

Снимок экрана: проводник с изображением папки развертывания с двумя выделенными файлами JavaScript Hello Word.

Неправильно считать, что вы сэкономили более 300 КБ. Обеим веб-частям по-прежнему нужен Angular, и он будет загружен, когда пользователь перейдет на страницу с одной из веб-частей.

Angular, выделенный в средствах разработчика, для страницы с одной веб-частью

Даже если вы добавите на страницу обе веб-части Angular, SharePoint Framework скачает Angular только один раз.

Angular, выделенный в средствах разработчика, для страницы с двумя веб-частями

Ссылаться на существующие библиотеки JavaScript как внешние ресурсы особенно удобно, если ваша организация хранит все распространенные сценарии вместе или вы используете CDN. В таком случае определенная библиотека JavaScript может уже быть в кэше браузера пользователя. В результате нужно загрузить только пакет веб-части, что ускоряет загрузку страницы.

На вкладке средств разработчика

В предыдущем примере показано, как загрузить Angular из сети CDN, но использовать общедоступную сеть CDN не обязательно. В конфигурации можно указать любое расположение: общедоступную сеть CDN, частный репозиторий или библиотеку документов SharePoint. Для нормальной работы веб-частей необходимо, чтобы у пользователей был доступ к указанным URL-адресам.

Сети CDN оптимизированы для быстрой доставки ресурсов по всему миру. Преимущество общедоступных сетей CDN также в том, что определенный сценарий уже мог использоваться на другом веб-сайте, который посещал пользователь. Так как сценарий уже есть в локальном кэше браузера, его не нужно скачивать специально для веб-части, поэтому страница с веб-частью будет загружаться еще быстрее.

В некоторых организациях запрещен доступ к общедоступным CDN из корпоративной сети. В таких случаях распространенные платформы JavaScript можно хранить в частном репозитории. Так как библиотеки размещаются в вашей организации, вы сможете управлять заголовками кэша, чтобы повысить скорость загрузки ресурсов.

Форматы библиотек JavaScript

Разные библиотеки JavaScript создаются и упаковываются по-разному. Одни упаковываются как модули, а другие представляют собой простые сценарии, которые выполняются в глобальной области (их часто называют немодульными сценариями). При загрузке библиотек JavaScript с URL-адреса порядок регистрации внешнего сценария в проекте SharePoint Framework зависит от его формата. Существует несколько форматов модулей (AMD, UMD, CommonJS), но вам достаточно знать, является ли сценарий модулем.

При регистрации сценариев, упакованных в виде модулей, вам нужно лишь указать URL-адрес для скачивания сценария. Зависимости от других сценариев загружены в конструкцию модуля сценария.

Для немодульных сценариев необходимо указать по крайней мере URL-адрес для скачивания сценария и имя переменной для регистрации в глобальной области. Если немодульный сценарий зависит от других сценариев, их можно указать как зависимости. Рассмотрим несколько примеров.

Angular 1.x — это немодульный сценарий. Чтобы зарегистрировать его как внешний ресурс в проекте SharePoint Framework, необходимо указать его URL-адрес и имя глобальной переменной для регистрации:

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

Важно, чтобы имя, указанное в свойстве globalName , соответствовало имени, используемому скриптом. В этом случае другие сценарии, которые от него зависят, смогут получить к нему доступ.

ngOfficeUIFabric — директивы Angular для Office UI Fabric. Это модуль UMD, который зависит от Angular. Зависимость от Angular уже загружена в модуль, поэтому для его регистрации вам нужно лишь указать его URL-адрес:

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

jQuery — это сценарий AMD. Вот как его можно зарегистрировать:

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

Теперь представим, что вы хотите использовать jQuery с подключаемым модулем jQuery, который распространяется как немодульный сценарий.

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

"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"
}

Сообщение об ошибке при загрузке веб-части с помощью немодульного подключаемого модуля jQuery

Как упоминалось ранее, платформа SharePoint Framework позволяет указать зависимости для немодульных подключаемых модулей. Эти зависимости задаются с помощью свойства globalDependencies:

"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" ]
}

Каждая зависимость, указанная в свойстве globalDependencies, должна указывать на другую зависимость в разделе externals файла config/config.json.

Теперь при сборке проекта появится другое сообщение об ошибке, в котором будет указано, что невозможно задать зависимость от немодульного сценария.

Ошибка при сборке проекта SharePoint Framework с зависимостью немодульного сценария от модульного

Чтобы устранить эту проблему, достаточно зарегистрировать jQuery как немодульный сценарий.

"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" ]
}

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

Примечание.

Обратите внимание, что запись для регистрации jQuery использует jquery для имени внешнего ресурса, но jQuery в качестве имени глобальной переменной. Имя внешнего ресурса — это имя, используемое import в инструкциях в коде. Это также имя, которое должно соответствовать объявлениям типов TypeScript. Имя глобальной переменной, заданное globalName с помощью свойства, — это имя, известное другим скриптам, например подключаемым модулям, встроенным поверх библиотеки. Хотя для некоторых библиотек эти имена могут быть одинаковыми, они не требуются, и вам следует тщательно проверить, используются ли правильные имена, чтобы избежать проблем.

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

Рекомендации в отношении немодульных сценариев

Многие из разработанных ранее библиотек и сценариев JavaScript распространяются в виде немодульных сценариев. На платформе SharePoint Framework можно загружать немодульные сценарии, но лучше их не использовать.

Скрипты, не относящиеся к модулям, регистрируются в глобальной области страницы: скрипт, загруженный одной веб-частью, доступен для всех остальных веб-частей на странице. Если у вас есть две веб-части, использующие разные версии jQuery, которые загружаются как скрипты, не относящиеся к модулю, веб-часть, загружающая последнюю, перезаписывает все ранее зарегистрированные версии jQuery.

Как вы понимаете, результаты будут непредсказуемыми. Трудно отслеживать ошибки, возникающие только в определенных ситуациях (например, когда другие веб-части на странице используют другую версию jQuery и загружаются в определенном порядке). Для решения этой проблемы созданы модули: в них сценарии изолируются и не могут влиять друг на друга.

Рекомендации по объединению

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

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

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

Сводка

Для создания клиентских веб-частей на платформе SharePoint Framework можно использовать имеющиеся библиотеки JavaScript. Платформа SharePoint Framework позволяет объединять эти библиотеки вместе с веб-частями или загружать их как внешний ресурс. Мы рекомендуем загружать существующие библиотеки с URL-адреса, но иногда можно объединить их в пакет. Оцените свои потребности, чтобы выбрать наиболее подходящий способ.

См. также