Интеграция задач gulp в цепочку инструментов SharePoint Framework

Средства разработки клиентских приложений для SharePoint позволяют применять gulp для запуска следующих задач по сборке:

• добавление в пакет и минификация файлов JavaScript и CSS;
• запуск инструментов для вызова задач по добавлению в пакет и минификации перед каждой сборкой;
• компиляция файлов LESS или SASS в CSS;
• компиляция файлов TypeScript в JavaScript.

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

Задачи gulp

Обычно задачи gulp определяются в gulpfile.js следующим образом:

gulp.task('somename', function() {
  // Do stuff
});

При работе с цепочкой инструментов SharePoint Framework необходимо определить задачи в конвейере сборки платформы. После определения и регистрации в конвейере задача добавляется в цепочку инструментов.

В SharePoint Framework используется обычная цепочка инструментов сборки, которая состоит из набора пакетов npm с общими задачами сборки. Задачи по умолчанию определяются в обычном пакете, в отличие от ситуации, когда используется gulpfile.js клиентского проекта. Чтобы просмотреть доступные задачи, выполните следующую команду в консоли для каталога проекта:

gulp --tasks

Эта команда перечисляет все доступные задачи.

Специальные задачи gulp

Для добавления специальных задач нужно определить их в gulpfile.js.

Откройте gulpfile.js в редакторе кода. Код по умолчанию инициализирует цепочку инструментов SharePoint Framework и глобальный экземпляр gulp для этой цепочки. Любые добавляемые специальные задачи необходимо определять до инициализации глобального экземпляра gulp.

Добавление специальной задачи

Для добавления специальной задачи gulp добавьте новую подзадачу в конвейер сборки SharePoint Framework с помощью функции build.subTask.

let helloWorldSubtask = build.subTask('log-hello-world-subtask', function(gulp, buildOptions, done) {
  this.log('Hello, World!');
  // use functions from gulp task here
  done();
});

Если используется поток, будет возвращен поток:

let helloWorldSubtask = build.subTask('log-hello-world-subtask', function(gulp, buildOptions, done) {
  return gulp.src('images/*.png')
             .pipe(gulp.dest('public'));
});

Регистрация задачи с помощью командной строки gulp

После определения специальной задачи ее можно зарегистрировать с помощью командной строки gulp, используя функцию build.task().

// Register the task with gulp command line
let helloWorldTask = build.task('hello-world', helloWorldSubtask);

Примечание.

Любые добавляемые специальные задачи необходимо определять до инициализации глобального экземпляра gulp, т. е. перед такой строкой кода: build.initialize(gulp);

Теперь можно выполнить специальную команду в командной строке следующим образом:

gulp hello-world

Примечание.

Невозможно выполнить подзадачу, зарегистрированную с помощью функции build.subTask(), непосредственно в командной строке. Можно выполнить только задачу, зарегистрированную с помощью функции build.task().

Внесение записей журнала в процесс сборки SharePoint Framework

Чтобы добавить собственные сообщения журнала в процесс сборки SharePoint Framework, можно использовать указанные ниже методы в специальной задаче:

• log(message: string): заносит в журнал сообщение;
• logWarning(message: string): заносит в журнал предупреждение и добавляет его в список предупреждений, что приводит к сбою сборки;
• logError(message: string): заносит в журнал ошибку и добавляет ее в список ошибок, что приводит к сбою сборки;
• fileWarning(filePath: string, line: number, column: number, warningCode: string: message: string): заносит в журнал предупреждение, связанное с определенным файлом, и вызывает сбой сборки;
• fileError(filePath: string, line: number, column: number, warningCode: string: message: string): заносит в журнал ошибку, связанную с определенным файлом, и вызывает сбой сборки.

Пример.

let helloWorldSubtask = build.subTask('log-hello-world-subtask', function(gulp, buildOptions, done) {
  this.log('Logs message');
  this.logWarning('Logs a warning');
  this.logError('Logs an error');

  done();
});

Выполнение специальной задачи до или после доступных задач

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

• общая задача сборки (содержит все доступные задачи);
• задача TypeScript.

Задачи SharePoint Framework доступны на платформе сборки по умолчанию. Платформа сборки — это коллекция задач, определенных для конкретной цели (в нашем случае это сборка пакетов на стороне клиента). Доступ к платформе по умолчанию, а также к функциям выполнения до и после задачи можно получить с помощью объекта build.rig.

// execute before the TypeScript subtask
build.rig.addPreBuildTask(helloWorldTask);

// execute after TypeScript subtask
build.rig.addPostTypescriptTask(helloWorldTask);

// execute after all build tasks
build.rig.addPostBuildTask(helloWorldTask);

Пример. Специальная задача по изменению размера изображения

В качестве примера используем задачу gulp по изменению размера изображения. Это простая задача по изменению размера изображения.

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

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

var gulp = require('gulp');
var imageResize = require('gulp-image-resize');

gulp.task('default', function () {
  gulp.src('test.png')
      .pipe(imageResize({
        width : 100,
        height : 100,
        crop : true,
        upscale : false
      }))
      .pipe(gulp.dest('dist'));
});

Мы используем эти сведения для добавления данной задачи в проект с помощью функций build.subTask() и build.task():

var imageResize = require('gulp-image-resize');

let imageResizeSubTask = build.subTask('image-resize-subtask', function(gulp, buildOptions, done){
    return gulp.src('images/*.jpg')
               .pipe(imageResize({
                   width: 100,
                   height: 100,
                   crop: false
               }))
               .pipe(gulp.dest(path.join(buildOptions.libFolder, 'images')))
});

let imageResizeTask = build.task('resize-images', imageResizeSubTask);

Так как мы определяем поток, мы возвращаем его в конвейер сборки в функции build.subTask(). Затем конвейер сборки асинхронно выполняет этот поток gulp.

После этого можно выполнить задачу в командной строке gulp следующим образом:

gulp resize-images

Эта задача resize-images отображается также в списке доступных задач проекта при выполнении gulp --tasks.

См. также

• Обзор SharePoint Framework