在 SharePoint 框架工具链中集成 Gulp 任务

SharePoint 客户端开发工具使用 gulp 作为生成过程任务运行程序，以执行以下操作：

• 捆绑和缩小 JavaScript 与 CSS 文件。
• 在每次生成前运行工具以调用捆绑和缩小任务。
• 将 LESS 或 Sass 文件编译为 CSS。
• 将 TypeScript 文件编译为 JavaScript。

可以在 SharePoint 框架工具链中添加一个常见任务，具体方法是在生成管道中集成自定义 Gulp 任务。

Gulp 任务

Gulp 任务在 gulpfile.js 中的常规定义为：

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

使用 SharePoint 框架工具链时，需要在框架的生成管道中定义任务。 在管道中定义和注册任务后，便可以将其添加到工具链中。

SharePoint 框架使用通用生成工具链，其中包含一组共享常见生成任务的 npm 包。 默认任务是在通用包中定义，而不是在客户端项目的 gulpfile.js 中定义。 若要查看可用任务，可以在控制台中的项目目录内执行以下命令：

gulp --tasks

此命令将列出所有可用任务。

自定义 Gulp 任务

若要添加自定义任务，请在 gulpfile.js 中定义自定义任务。

在代码编辑器中打开 gulpfile.js。 默认代码可初始化 SharePoint 框架工具链及其全局 gulp 实例。 应先定义添加的所有自定义任务，然后再初始化全局 gulp 实例。

添加自定义任务

若要添加自定义 Gulp 任务，请使用 build.subTask 函数将新的子任务添加到 SharePoint 框架生成管道中：

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 框架构建流程

若要将自己的日志记录消息添加到 SharePoint 框架构建流程，可以在自定义任务中使用以下方法：

• 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 框架任务位于默认生成 rig 中。 生成 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 框架概述