Fork me on GitHub

gulp常用插件之gulp-inject使用

更多gulp常用插件使用请访问：gulp常用插件汇总

gulp-inject这个插件的作用与wiredep类似，不同的是可以自己任意指定需要插入文件的列表。它同样是利用注释来寻找插入的位置。获取源文件流，将每个文件转换为字符串，并将每个转换后的字符串注入目标流文件中的占位符。

更多使用文档请点击访问gulp-inject工具官网。

同样是利用注释来寻找插入的位置，它识别的默认注释为，但更加智能：

  • 支持各种模板语言：可以根据gulp.src指定的源文件自动识别注释和插入内容，除了支持HTML外，还支持jade、haml等。若源为jade文件，则识别的注释为//- inject:js，插入的内容为：script(src=".js")。
  • 配置非常灵活：
    • name：默认识别的注释标签格式为，这里的name默认值就是“inject”，而ext的默认值是要插入的文件的扩展名。那么name属性可配置意味着可以添加自定义的插入区块，如，这个标签可以只插入生产环境需要包含的JS文件。
    • starttag 和 endtag：支持自定义需要识别的注释内容。
    • addPrefix 和 addSuffix：支持在插入文件的路径上自定义前缀、后缀。
    • relative：指定插入文件的路径是否为相对路径。
    • ingorePath：指定插入文件的路径前面会忽略掉指定的路径。
    • read：这个参数通常给false，不需要真正的去读取文件。

安装

一键安装不多解释

npm install --save-dev gulp-inject

使用

目标文件src/index.html：

每对注释都是注入占位符

<!DOCTYPE html>
<html>
<head>
  <title>My index</title>
  <!-- inject:css -->
  <!-- endinject -->
</head>
<body>

  <!-- inject:js -->
  <!-- endinject -->
</body>
</html>

在gulpfile.js:

var gulp = require('gulp');
var inject = require('gulp-inject');

gulp.task('index', function () {
  var target = gulp.src('./src/index.html');
  //不需要读取文件（这会加快速度），我们只需要查看它们的路径：
  var sources = gulp.src(['./src/**/*.js', './src/**/*.css'], {read: false});

  return target.pipe(inject(sources))
    .pipe(gulp.dest('./src'));
});

执行gulp命令之后index.html:

<!DOCTYPE html>
<html>
<head>
  <title>My index</title>
  <!-- inject:css -->
  <link rel="stylesheet" href="/src/style1.css">
  <link rel="stylesheet" href="/src/style2.css">
  <!-- endinject -->
</head>
<body>

  <!-- inject:js -->
  <script src="/src/lib1.js"></script>
  <script src="/src/lib2.js"></script>
  <!-- endinject -->
</body>
</html>

更多例子：

相对于目标文件注入文件

默认情况下，注入的文件路径是相对于每个源文件的路径cwd。如果options.relative设置为true ，则每个注入的路径将相对于每个目标文件的目录。

项目结构：

└── src
    ├── module
    │   ├── module.js
    │   └── module.html
    └── app
        ├── main.js
        └── index.html

src/app/index.html：

<!DOCTYPE html>
<html>
<head>
  <title>My Index</title>
</head>
<body>
  <h1>Home</h1>
  <!-- inject:js -->
  <!-- endinject -->
</body>
</html>

src/module/module.html：

<!DOCTYPE html>
<html>
<head>
  <title>Module</title>
</head>
<body>
  <h1>Module</h1>
  <!-- inject:js -->
  <!-- endinject -->
</body>
</html>

gulpfile.js：

var inject = require('gulp-inject');

gulp.src('./src/**/*.html')
  .pipe(inject(gulp.src('./src/**/*.js', {read: false}), {relative: true}))
  .pipe(gulp.dest('./src'));

结果src/app/index.html：

<!DOCTYPE html>
<html>
<head>
  <title>My Index</title>
</head>
<body>
  <h1>Home</h1>
  <!-- inject:js -->
  <script src="main.js"></script>
  <script src="../module/module.js"></script>
  <!-- endinject -->
</body>
</html>

结果src/module/module.html：

<!DOCTYPE html>
<html>
<head>
  <title>Module</title>
</head>
<body>
  <h1>Home</h1>
  <!-- inject:js -->
  <script src="../app/main.js"></script>
  <script src="module.js"></script>
  <!-- endinject -->
</body>
</html>

从多个源流注入文件

此示例演示如何将来自多个不同流的文件注入到同一注入占位符。

安装event-stream方式：npm install --save-dev event-stream并使用其merge功能。

代码：

var es = require('event-stream'),
    inject = require('gulp-inject'),
    concat = require('gulp-concat'),
    uglify = require('gulp-uglify');

// 连接供应商脚本
var vendorStream = gulp.src(['./src/vendors/*.js'])
  .pipe(concat('vendors.js'))
  .pipe(gulp.dest('./dist'));

// 连接和缩小应用程序源
var appStream = gulp.src(['./src/app/*.js'])
  .pipe(concat('app.js'))
  .pipe(uglify())
  .pipe(gulp.dest('./dist'));

gulp.src('./src/index.html')
  .pipe(inject(es.merge(vendorStream, appStream)))
  .pipe(gulp.dest('./dist'));

订单重要时有多个来源
使用stream-series。

var series = require('stream-series'),
    inject = require('gulp-inject');

var vendorStream = gulp.src(['./src/vendors/*.js'], {read: false});

var appStream = gulp.src(['./src/app/*.js'], {read: false});

gulp.src('./src/index.html')
  .pipe(inject(series(vendorStream, appStream))) //这将始终在应用程序文件之前注入供应商文件
  .pipe(gulp.dest('./dist'));

注入一些文件到<head>一些成<body>

方法1：使用gulp-inject的starttag选项。
gulpfile.js：

var inject = require('gulp-inject');

gulp.src('./src/index.html')
  .pipe(inject(gulp.src('./src/importantFile.js', {read: false}), {starttag: '<!-- inject:head:{{ext}} -->'}))
  .pipe(inject(gulp.src(['./src/*.js', '!./src/importantFile.js'], {read: false})))
  .pipe(gulp.dest('./dist'));

并在您的./src/index.html：

<!DOCTYPE html>
<html>
<head>
  <title>My index</title>
  <!-- inject:head:js -->
  <!-- only importantFile.js will be injected here -->
  <!-- endinject -->
</head>
<body>

  <!-- inject:js -->
  <!-- the rest of the *.js files will be injected here -->
  <!-- endinject -->
</body>
</html>

方法2：使用gulp-inject的name选项。
gulpfile.js：

var inject = require('gulp-inject');

gulp.src('./src/index.html')
  .pipe(inject(gulp.src('./src/importantFile.js', {read: false}), {name: 'head'}))
  .pipe(inject(gulp.src(['./src/*.js', '!./src/importantFile.js'], {read: false})))
  .pipe(gulp.dest('./dist'));

并在您的./src/index.html：

<!DOCTYPE html>
<html>
<head>
  <title>My index</title>
  <!-- head:js -->
  <!-- only importantFile.js will be injected here -->
  <!-- endinject -->
</head>
<body>

  <!-- inject:js -->
  <!-- the rest of the *.js files will be injected here -->
  <!-- endinject -->
</body>
</html>

注入所有文件进行开发
如果您将Bower用于前端依赖项，我建议也使用main-bower-files和注入它们。

gulpfile.js：

var bowerFiles = require('main-bower-files'),
    inject = require('gulp-inject'),
    stylus = require('gulp-stylus'),
    es = require('event-stream');

var cssFiles = gulp.src('./src/**/*.styl')
  .pipe(stylus())
  .pipe(gulp.dest('./build'));

gulp.src('./src/index.html')
  .pipe(inject(gulp.src(bowerFiles(), {read: false}), {name: 'bower'}))
  .pipe(inject(es.merge(
    cssFiles,
    gulp.src('./src/app/**/*.js', {read: false})
  )))
  .pipe(gulp.dest('./build'));

src/index.html：

<!DOCTYPE html>
<html>
<head>
  <title>My index</title>
  <!-- bower:css -->
  <!-- bower installed css files will go here... -->
  <!-- endinject -->
  <!-- inject:css -->
  <!-- built css files will go here... -->
  <!-- endinject -->
</head>
<body>

  <!-- bower:js -->
  <!-- bower installed scripts will go here... -->
  <!-- endinject -->
  <!-- inject:js -->
  <!-- app scripts will go here... -->
  <!-- endinject -->
</body>
</html>

请注意，请记住在服务器上挂载./bower_components，./build并将其./src/app作为静态资源以使其正常工作。

注入一个json文件

您可以gulp-inject使用transformfunction选项进一步定制，例如，将文件注入json文件。
代码如下：

gulp.src('./files.json')
  .pipe(inject(gulp.src(['./src/*.js', './src/*.css', './src/*.html'], {read: false}), {
    starttag: '"{{ext}}": [',
    endtag: ']',
    transform: function (filepath, file, i, length) {
      return '  "' + filepath + '"' + (i + 1 < length ? ',' : '');
    }
  }))
  .pipe(gulp.dest('./'));

初始内容files.json：

{
   “ js ”：[
  ]，
  “ css ”：[
  ]，
  “ html ”：[
  ]
}

transform使用默认回退的自定义功能进行注入

该默认transform功能可使用例如作为默认的备用。

在此处用于将Word文档作为<a>以下标记注入：

index.html：

<!DOCTYPE html>
<html>
<head>
  <title>My documents</title>
</head>
<body>
  <h1>Documents</h1>
  <ul>
    <!-- inject:docx -->
    <!-- endinject -->
  </ul>
  <!-- inject:js -->
  <!-- endinject -->
</body>
</html>

gulpfile.js:

var inject = require('gulp-inject');

gulp.src('./index.html')
  .pipe(inject(
    gulp.src(['./*.js', './docs/*.docx'], {read: false}), {
      transform: function (filepath) {
        if (filepath.slice(-5) === '.docx') {
          return '<li><a href="' + filepath + '">' + filepath + '</a></li>';
        }
        // Use the default transform as fallback:
        return inject.transform.apply(inject.transform, arguments);
      }
    }
  ))
  .pipe(gulp.dest('./'));

运行结束的index.html:

<!DOCTYPE html>
<html>
<head>
  <title>My documents</title>
</head>
<body>
  <h1>Documents</h1>
  <ul>
    <!-- inject:docx -->
    <li><a href="/docs/document1.docx"></a></li>
    <li><a href="/docs/document2.docx"></a></li>
    <!-- endinject -->
  </ul>
  <!-- inject:js -->
  <script src="/lib1.js"></script>
  <script src="/lib2.js"></script>
  <!-- endinject -->
</body>
</html>

将dist文件注入bower.json的主要部分
代码如下：

gulp.src('./bower.json')
  .pipe(inject(gulp.src(['./dist/app.min.js', './dist/app.min.css'], {read: false}), {
    starttag: '"main": [',
    endtag: ']',
    transform: function (filepath, file, i, length) {
      return '  "' + filepath + '"' + (i + 1 < length ? ',' : '');
    }
  }))
  .pipe(gulp.dest('./'));

将所有javascript文件注入到业力配置文件中
代码如下：

gulp.src('./karma.conf.js')
  .pipe(inject(gulp.src(['./src/**/*.js'], {read: false}), {
    starttag: 'files: [',
    endtag: ']',
    transform: function (filepath, file, i, length) {
      return '  "' + filepath + '"' + (i + 1 < length ? ',' : '');
    }
  }))
  .pipe(gulp.dest('./'));

注入文件内容
为了注入文件内容，您必须提供自定义transform功能，该功能将以字符串形式返回文件内容。在这种情况下，您还必须省略{read: false}选项gulp.src。以下示例显示了如何将html局部内容注入到head中index.html：

gulp.src('./src/index.html')
  .pipe(inject(gulp.src(['./src/partials/head/*.html']), {
    starttag: '<!-- inject:head:{{ext}} -->',
    transform: function (filePath, file) {
      // return file contents as string
      return file.contents.toString('utf8')
    }
  }))
  .pipe(gulp.dest('./dest'));

./src/index.html：

<!DOCTYPE html>
<html>
<head>
  <title>My index</title>
  <!-- inject:head:html -->
  <!-- contents of html partials will be injected here -->
  <!-- endinject -->
</head>
<body>
</body>
</html>

根据文件路径注入文件内容

为了根据文件路径注入文件，您必须提供自定义starttag，其中包括{{path}}。另外，为了注入文件内容包括transform函数，该函数将以字符串形式返回文件内容。在这种情况下，您还必须省略{read: false}选项gulp.src。路径可以是绝对路径，也可以是相对路径，在这种情况下，应将[ options.relative] 设置为true。以下示例显示了如何将html局部内容注入到index.html：
代码如下：

gulp.src('./src/index.html')
  .pipe(inject(gulp.src(['./src/partials/head/*.html']), {
    starttag: '<!-- inject:{{path}} -->',
    relative: true,
    transform: function (filePath, file) {
      // return file contents as string
      return file.contents.toString('utf8')
    }
  }))
  .pipe(gulp.dest('./dest'));

./src/index.html:

<!DOCTYPE html>
<html>
<head>
  <title>My index</title>
  <!-- inject:path/to/your/file.ext -->
  <!-- contents of html partials will be injected here -->
  <!-- endinject -->
</head>
<body>
</body>
</html>

API

inject(sources, options)
  • 参数: sources
    类型: Stream
    提供Vinyl File Stream作为输入inject，请参见上面的示例。
  • 参数: options
    类型: Object

options参数详解

  • options.ignorePath
    类型：String或Array
    默认： NULL
    应从每个插入的文件路径中删除的一个或多个路径。
    这也可以通过cwd为gulp.src流设置选项来解决，cwd在注入之前，每个源文件都会自动从其路径中删除（如果未options.relative设置为true，请参见下文）。
  • options.relative
    类型：Boolean
    默认： false
    如果将true注入文件的路径设置为相对于每个目标文件的路径，则这也意味着cwd不必从其路径中删除每个源文件。
  • options.addPrefix
    类型： String
    默认： NULL
    应在每个注入的文件路径之前添加路径。
    *options.addSuffix
    类型： String
    默认： NULL
    每个注入的文件路径均应添加后缀的路径。
  • options.addRootSlash
    类型： Boolean
    默认： !options.relative
    根斜杠会自动添加到路径（'/'）的开头，如果设置为，则将其删除false。
  • options.name
    类型： String
    默认： "inject"
    在下面的默认starttag 和endtag标记中使用。
  • options.removeTags
    类型： Boolean
    默认： false
    当true注射文件时，开始和结束标记将被删除。
  • options.empty
    类型： Boolean
    默认： false
    当true所有没有相应文件的标签将被清空。

警告这可能会导致清空过多的问题。

  • options.starttag
    类型： String |Function(targetExt, sourceExt)
    参数（如果有功能）：

    • targetExt : 目标文件的文件扩展名
    • sourceExt : 源文件的文件扩展名

    目的：
    用于根据文件扩展名动态设置起始占位符标签。在提供的字符串或从给定函数返回的字符串中，该字符串{{ext}}将替换为源文件扩展名，例如“ css”，“ js”或“ html”。{{name}}将由取代options.name。{{path}}将被源文件的路径替换（当与[options.relative] 一起使用时，将允许源文件的相对路径。
    默认：
    取决于目标文件类型和源文件类型的函数返回：

    1. 以html为目标： <!-- {{name}}:{{ext}} -->
    2. haml作为目标： -# {{name}}:{{ext}}
    3. 玉为目标： //- {{name}}:{{ext}}
    4. 哈巴狗为目标： //- {{name}}:{{ext}}
    5. jsx作为目标： {/* {{name}}:{{ext}} */}
    6. slm作为目标： / {{name}}:{{ext}}
    7. 少于目标：/* {{name}}:{{ext}} */
    8. sass，scss作为目标： /* {{name}}:{{ext}} */

  • options.endtag
    类型：String |Function(targetExt, sourceExt)
    参数（如果有功能）：

    • targetExt : 目标文件的文件扩展名
    • sourceExt : 源文件的文件扩展名

    目的：
    用于根据文件扩展名动态设置结尾占位符标签。在提供的字符串或从给定函数返回的字符串中，该字符串{{ext}}将替换为源文件扩展名，例如“ css”，“ js”或“ html”。{{name}}将由取代options.name。{{path}}将替换为源文件的路径。
    默认：
    取决于目标文件类型和源文件类型的函数返回：

    1. 以html为目标： <!-- endinject -->
    2. haml作为目标： -# endinject
    3. 玉为目标： //- endinject
    4. 哈巴狗为目标： //- endinject
    5. jsx作为目标： {/* endinject */}
    6. slm作为目标：/ endinject
    7. 少于目标： /* endinject */
    8. sass，scss作为目标： /* endinject */

  • options.transform
    类型：Function(filepath, file, index, length, targetFile)
    参数：

    • filepath : ignorePath删除addPrefix并addSuffix添加了任何的文件的“ unixified”路径
    • file : 要注入的File对象来自gulp.src
    • index : 从0开始的文件索引
    • length : 当前文件扩展名要注入的文件总数
    • targetFile : 要注入的目标文件

    目的：
    用于生成要为每个文件注入的内容。
    默认：
    取决于目标文件类型和源文件类型的函数返回：

    注入 html

    • CSS文件： <link rel="stylesheet" href="<filename>.css">
    • js文件： <script src="<filename>.js"></script>
    • 咖啡档案： <script type="text/coffeescript" src="<filename>.coffee"></script>
    • html文件： <link rel="import" href="<filename>.html">
    • png文件： <img src="<filename>.png">
    • gif文件： <img src="<filename>.gif">
    • jpg文件： <img src="<filename>.jpg">
    • jpeg文件： <img src="<filename>.jpeg">

    如果options.selfClosingTag为，true则上面的默认转换器将使<link>和<img>标签自闭，即分别为：<link ... />和<img ... />。

    注入 jsx
    html与options.selfClosingTag设置为的上述注入相同true。

    注入 jade

    • CSS文件： link(rel="stylesheet", href="<filename>.css")
    • js文件： script(src="<filename>.js")
    • 咖啡档案： script(type="text/coffeescript", src="<filename>.coffee")
    • html文件：link(rel="import", href="<filename>.html")
    • png文件： img(src="<filename>.png")
    • gif文件： img(src="<filename>.gif")
    • jpg文件： img(src="<filename>.jpg")
    • jpeg文件： img(src="<filename>.jpeg")

    注入 pug

    • CSS文件： link(rel="stylesheet", href="<filename>.css")
    • js文件： script(src="<filename>.js")
    • 咖啡档案： script(type="text/coffeescript", src="<filename>.coffee")
    • html文件： link(rel="import", href="<filename>.html")
    • png文件： img(src="<filename>.png")
    • gif文件： img(src="<filename>.gif")
    • jpg文件： img(src="<filename>.jpg")
    • jpeg文件： img(src="<filename>.jpeg")

    注入 slm

    • CSS文件： link rel="stylesheet" href="<filename>.css"
    • js文件： script src="<filename>.js"
    • 咖啡档案： script type="text/coffeescript" src="<filename>.coffee"
    • html文件： link rel="import" href="<filename>.html"
    • png文件： img src="<filename>.png"
    • gif文件： img src="<filename>.gif"
    • jpg文件： img src="<filename>.jpg"
    • jpeg文件： img src="<filename>.jpeg"

    注入 haml

    • CSS文件： %link{rel:"stylesheet", href:"<filename>.css"}
    • js文件： %script{src:"<filename>.js"}
    • 咖啡档案： %script{type:"text/coffeescript", src:"<filename>.coffee"}
    • html文件： %link{rel:"import", href:"<filename>.html"}
    • png文件： %img{src:"<filename>.png"}
    • gif文件： %img{src:"<filename>.gif"}
    • jpg文件： %img{src:"<filename>.jpg"}
    • jpeg文件： %img{src:"<filename>.jpeg"}

    注入 less
    CSS文件： @import "<filename>.css";
    较少的文件： @import "<filename>.less";

    注入 scss
    CSS文件： @import "<filename>.css";
    scss文件： @import "<filename>.scss";
    sass文件： @import "<filename>.sass";

    注入 sass
    CSS文件： @import "<filename>.css"
    sass文件： @import "<filename>.sass"
    scss文件： @import "<filename>.scss"

  • options.selfClosingTag
    类型：Boolean
    默认： false
    影响默认options.transform功能，请参见上文。

  • options.quiet
    类型： Boolean
    默认： false
    通过将其设置为true可以降低详细程度，从而抑制成功注射的记录。

  • inject.transform
    默认转换函数在公共API中公开。

    • nject.transform.html
      默认的将文件转换为html或其他文件类型的转换函数，而不是jade、pug、jsx、slm、less、scss、sass或haml。
    • inject.transform.jade
      文件的默认转换功能为jade
    • inject.transform.pug
      文件的默认转换功能为pug
    • inject.transform.jsx
      文件的默认转换功能为jsx
    • inject.transform.slm
      文件的默认转换功能为slm
    • inject.transform.haml
      文件的默认转换功能为haml
    • inject.transform.less
      文件的默认转换功能为less
    • inject.transform.sass
      文件的默认转换功能为sass
    • inject.transform.scss
      文件的默认转换功能为scss
posted @ 2019-12-27 17:32  较瘦  阅读(1842)  评论(0)  编辑  收藏  举报
知识点文章整理