TAT.mandyluo gulp 进阶-自定义 gulp 插件
In Web开发 on 2016年01月24日 by view: 4,863
10

gulp 已经成为很多项目的标配了,gulp 的插件生态也十分繁荣,截至 2015.1.5,npm 上已经有 10190 款 gulp 插件供我们使用。我们完全可以傻瓜式地搭起一套构建。

然而,我们经常会遇到一种情况,我们好不容易按照文档传入对应的参数调用了插件,却发现结果不如预期,这时候我们就要一点点去排错,这就要求我们对 gulp 插件的工作原理有一定的了解。本文以实现一个 gulp 插件为例,讲解一下 gulp 插件是如何工作的。

需求描述

通常,我们的构建资源为 js/css/html 以及其它的一些资源文件,在开发或发布阶段,js/css 会经过合并, 压缩, 重命名等处理步骤。

有些场景下,我们不能确定经过构建后生成 js/css 的名称或者数量,如此就不能在 HTML 文件中写死资源的引用地址,那么该如何实现一个 Gulp 的插件用以将最终生成的资源文件/地址注入到 HTML 中呢?

假设我们需要实现的插件是这样使用方式:

我们通过一个 HTML 注释用以声明需要依赖的资源,InlineResource 是匹配的关键词,":" 做为分割,/*.css$/,/*.js$/ 是声明要依赖的文件的正则匹配。

在 gulpfile.js 我们需要这边配置:

这里简单介绍下其中的一些方法与步骤:

  • gulp.src('index.html')  会读取文件系统中当前目录下的 index.html,并生成一个可读的 Stream,用于后续的步骤消费

  • InjectResources(stream)  是我们将要实现的插件,它接受一个参数用以获取要注入到 HTML 中的 JS/CSS,此参数应该是一个 Stream  实例,用生成一个 Stream 实例,用于接收并处理上一步流进来的数据

  • hash(options)  是一个第三方插件,用于往当前流中的文件名添加 md5 串,如:gulp-hash

  • gulp.dest('dist')  用于将注入资源后的 HTML 文件生成到当前目录下

我们要关心的是第 2 点:如何接所有的资源文件并完成注入?

我们可以将该逻辑分成 4 个步骤

  1. 获取所有的 js/css 资源
  2. 获取所有的 HTML 文件
  3. 定位 HTML 中的依赖声明
  4. 匹配所依赖的资源
  5. 生成并注入依赖的资源标签

在开编之前,我们需要依赖一个重要的第三方库:map-stream

map-stream  用于获取当前流中的每一个文件数据,并且修改数据内容。

步骤 1 (JS/CSS 资源)

资源流会作为参数的形式传给 InjectResources 方法,在此通过一个异步的实例方法获取所有的文件对象,放到一个资源列表:

  • mapStream 的处理方法中获取到的 data 是由 gulp.src 生成的 vinyl 对象,代表了一个文件
  • 每一个 stream 都会在接受后抛出 end 事件

Note: mapStream 的处理方法中的 cb 方法,第二个参数可以用于替换当前处理的文件对象

到此,我们就完成了第一步的封装啦!

步骤 2 (HTML 文件)

InjectResources 插件方法会返回一个 Writable Stream 实例,用于接收并处理流到 InjectResources 的 HTML 文件,mapStream 的返回值就是一个 writable stream。

此时,mapStream 的处理方法拿到的 data 就是一个 HTML 文件对象,接下来进行内容处理。

步骤 3 (定位依赖)

我们拿到的 data 是一个 vinyl 对象,contents 属性是文件的内容,类型可能是 Buffer 也可能是 String, 通过 toStraing() 后可以获取到字符串内容。

所有的依赖声明都有 InlineResource 关键词,简单点的做法,可以通过正则来定位并替换 HTML 中的资源依赖:

到此,我们完成了资源依赖的定位,下一步将是获取所依赖的资源用以替换。

步骤 4 (依赖匹配)

我们将通过步骤 1 定义的 getResources 方法获取所需的资源文件:

由于 getResources 是异步方法,因此需要把替换处理逻辑包裹在 getResources 的回调方法中

根据依赖声明中的正则表达式,对资源列表一一匹配:

到此只差最后一步,将资源转换为 HTML 标签并注入到 HTML 中

步骤 5 (资源转换/依赖注入)

接下来的定义一个 transform 方法,用于将路径列表转换为 HTML 的资源标签列表,其中引入了 path  模块用于解析获取文件路径的一些信息,该模块是 node 内置模块。

最终,我们将标签列表拼接为一个字符串来 HTML 中的依赖声明(注入):

到此也就完整地实现了一个拥有基本注入功能的插件~~~~~~

One More Thing

通过上面实现的示例步骤,可以清楚了解到 gulp 插件的工作原理。 但要做一个易用/可定制性高的插件,我们还要继续完善一下,例如:

  • 比较资源的路径与 HTML 的路径,输出相对路径作为默认的标签资源路径
  • 提供 sort 选项方法用于修改资源的注入顺序
  • 提供 transform 选项方法用于定制标签中的资源路径
  • 在依赖声明中支持 inline 声明,用以将资源内容内联到 HTML 中,例如:

  • 支持命名空间,用于往同一个资源流中使用多次资源注入的区分,例如:

  • . . .

 

原创文章转载请注明:

转载自AlloyTeam:http://www.alloyteam.com/2016/01/9918/

  1. TransNet2013 2016 年 2 月 23 日

    推测是 2016.1.5 日,截止

    • TAT.mandyluo

      TAT.mandyluo 2016 年 2 月 24 日

      呃呃,原来已经 2016 了,光阴似箭,日月如梭

  2. shu 2016 年 2 月 2 日

    对于类似 browserify 的多级依赖,合并内容时不确定在 gulp 流中的顺序,该怎么处理好呢?

    • TAT.mandyluo

      TAT.mandyluo 2016 年 2 月 2 日

      在最后有提到,提供 sort 选项方法,让用户自定义资源顺序

  3. darcy.bai 2016 年 2 月 1 日

    if (resources) 这里有问题吧, 空数组为真吧.

  4. darcy 2016 年 1 月 28 日

    太赞了

  5. send 2016 年 1 月 25 日

    [good]

发表评论到 TAT.mandyluo