SharePoint Framework ツールチェーンにおける Gulp タスクの統合

SharePoint のクライアント側の開発ツールは、gulp をビルド プロセスのタスク ランナーとして使用し次のことを行います。

• JavaScript と CSS ファイルをバンドルし、縮小します。
• ツールを実行して、各ビルドの前にバンドル化タスクと縮小タスクを呼び出します。
• LESS または Sass ファイルを CSS にコンパイルします。
• TypeScript ファイルを JavaScript にコンパイルします。

SharePoint Framework ツールチェーンに追加する一般的なタスクの 1 つとして、ビルド パイプラインにカスタム 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 タスクを追加するには、build.subTask 関数を使用して SharePoint Framework ビルド パイプラインに新しいサブタスクを追加します。

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 コマンドラインでのタスクの登録

カスタム タスクの定義後、そのカスタム タスクは build.task() 関数を使用して Gulp コマンドラインで登録できます。

// 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 で利用できます。 build rig は、特定の目的のために定義されたタスク コレクションです。ここでは、クライアント側パッケージのビルドを目的としています。 build.rig オブジェクトを使用すると、この既定の 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

gulp --tasks を実行すると、プロジェクトで利用可能なタスクに、この resize-images タスクも表示されます。

関連項目

• SharePoint Framework の概要