Расширение конфигурации Webpack в цепочке инструментов SharePoint Framework

  • Статья

Webpack — это средство увязки модулей JavaScript в пакеты. На основе выбранных вами файлов JavaScript и их зависимостей это средство создает один или несколько файлов JavaScript, чтобы можно было загружать различные части кода для различных сценариев.

Для увязки файлов в пакеты цепочка инструментов платформы использует систему CommonJS. Это позволяет определять модули и указывать, где вы хотите использовать их. Кроме того, цепочка инструментов использует SystemJS (универсальный загрузчик модулей) для загрузки ваших модулей. Она помогает обеспечивает выполнение каждой веб-части в отдельном пространстве имен.

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

Использование загрузчиков Webpack

Во время разработки часто требуется импортировать и использовать ресурсы, не относящиеся к JavaScript, например изображения или шаблоны. Загрузчик Webpack преобразовывает ресурс так, что его сможет использовать ваше приложение JavaScript, либо предоставляет простую ссылку, понятную для приложения JavaScript.

Например, шаблон Markdown можно скомпилировать и преобразовать в текстовую строку, а ресурс изображения можно преобразовать во встроенное изображение в кодировке Base64. Кроме того, можно создать ссылку на ресурс изображения в виде URL-адреса и скопировать его в каталог dist для развертывания.

Существует много полезных загрузчиков. Некоторые из них уже используются в стандартной конфигурации Webpack в SharePoint Framework, среди них:

  • html-loader;
  • json-loader;
  • loader-load-themed-styles.

Расширение конфигурации Webpack платформы с помощью собственных загрузчиков — это простой процесс, описанный на этой странице.

Пример: использование пакета markdown-loader

В качестве примера рассмотрим пакет markdown-loader. Это загрузчик, который позволяет ссылаться на файл .md и выводить его в качестве строки HTML.

Вы можете скачать готовый образец по ссылке samples/js-extend-webpack.

Шаг 1. Установка пакета

Добавьте в проект ссылку на пакет markdown-loader:

npm i --save markdown-loader

Шаг 2. Настройка Webpack

Теперь, когда пакет markdown-loader установлен, давайте включим его в конфигурацию Webpack для SharePoint Framework.

В документации по пакету markdown-loader показано, как расширить конфигурацию Webpack, чтобы она включала загрузчик:

{
  module: {
    rules: [
      {
        test: /\.md$/,
        use: [
          {
            loader: 'html-loader'
          },
          {
            loader: 'markdown-loader',
            options: {
              /* options for markdown-loader here */
            }
          }
        ]
      }
    ]
  }
}

Давайте посмотрим, что делает эта конфигурация.

  • Массив rules в конфигурации Webpack определяет набор проверок путей к файлам и загрузчики, которые следует использовать при обнаружении ресурса, соответствующего условиям проверки. В этом случае свойство test выполняет проверку путей к файлам, которые заканчиваются на .md.
  • Массив use описывает список загрузчиков, которые последовательно применяются к ресурсу. Они применяются, начиная с последнего и заканчивая первым. В данном случае первым будет применен загрузчик markdown-loader, а последним — html-loader.
  • Если указано несколько загрузчиков, результаты работы каждого загрузчика передаются следующему.

Мы будем использовать эти сведения для настройки загрузчика в нашем проекте.

Чтобы добавить этот особый загрузчик в конфигурацию Webpack для SharePoint Framework, необходимо поручить задаче сборки настроить Webpack. Задачи сборки определяются в файле gulpfile.js, который находится в корневой папке проекта.

Измените файл gulpfile.js, добавив следующий код перед строкой build.initialize(gulp);:

build.configureWebpack.mergeConfig({
  additionalConfiguration: (generatedConfiguration) => {
    generatedConfiguration.module.rules.push(
      {
        test: /\.md$/,
        use: [
          {
            loader: 'html-loader'
          },
          {
            loader: 'markdown-loader'
          }
        ]
      }
    );

    return generatedConfiguration;
  }
});

Давайте разберем, что делает этот фрагмент кода.

  • Задача ConfigureWebpackTask (в виде экземпляра build.configureWebpack) настраивает Webpack. Существует много особых конфигураций для сборки проектов SPFx, поэтому в данной задаче используется нетривиальная логика.
  • Задача ConfigureWebpackTask принимает необязательное свойство additionalConfiguration. Нам необходимо указать в этом свойстве функцию, которая вносит изменения в созданную конфигурацию и возвращает обновленную конфигурацию. Эта функция должна возвращать конфигурацию Webpack в цепочку инструментов, в противном случае Webpack будет настроен неправильно.
  • В теле функции, которую мы задали для additionalConfiguration, просто отправьте новое правило в существующий набор правил в конфигурации. Обратите внимание, что это новое правило похоже на пример во фрагменте конфигурации в начале шага 2.

Примечание.

Используя этот подход, вы можете полностью заменить конфигурацию Webpack, используемую по умолчанию в цепочке инструментов, но для достижения максимальной производительности и оптимизации не рекомендуется делать это, если иное не указано в документации.

Шаг 3. Внесение изменений в код

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

  1. Создайте файл ./src/my-markdown.md с текстом Markdown.

    #Hello Markdown

*Markdown* is a simple markup format to write content.

You can also format text as **bold** or *italics* or ***bold italics***

При сборке проекта загрузчик markdown-loader Webpack преобразовывает этот текст в строку HTML.

  1. Чтобы использовать эту строку HTML в любом из ваших исходных файлов TS, добавьте следующую строку require() в начале файла после кода импорта:

    const markdownString: string = require<string>('./../../../../src/my-markdown.md');

    По умолчанию Webpack ищет файл в папке lib, но по умолчанию файлы .md не копируются в папку lib, поэтому необходимо составить довольно длинный относительный путь. Мы можем определить файл конфигурации, который даст цепочке инструментов указание копировать файлы md в папку lib.

  2. Создайте файл ./config/copy-static-assets.json, чтобы сообщить системе сборки, что необходимо скопировать некоторые дополнительные файлы из папки src в папку lib. Эта задача сборки копирует файлы с расширениями, которые понятны стандартной конфигурации Webpack цепочки инструментов (например, png и json), поэтому нам просто необходимо поручить ей скопировать файлы md.

    {
  "includeExtensions": [
    "md"
  ]
}

  3. Теперь в операторе require вместо относительного пути можно использовать путь к файлу, например:

    const markdownString: string = require<string>('./../../readme.md');

  4. Вы можете ссылаться на эту строку в коде, например:

    public render(): void {
  this.domElement.innerHTML = markdownString;
}

Шаг 4. Сборка и тестирование кода

Для сборки и проверки кода выполните следующую команду в корневой папке каталога проекта:

gulp serve

См. также