A grunt plugin to help front engineer creating css sprite.
CSS JavaScript HTML
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
tasks
test
Gruntfile.js
LICENSE-MIT
README.md
package.json

README.md

grunt-css-sprite

这是什么

这是一个帮助前端开发工程师将 css 代码中的切片合并成雪碧图的工具; 其灵感来源于 grunt-sprite,由于其配置参数限制目录结构等,不能满足通用项目需求,重新造轮子发布; 它的主要功能是:

  1. 对 css 文件进行处理,收集切片序列,生成雪碧图
  2. 在原css代码中为切片添加background-position属性
  3. 生成用于高清设备的高清雪碧图,并在css文件末尾追加媒体查询代码
  4. 生成高清设备雪碧图,使用 image-set
  5. 支持选择器提取,进一步优化CSS文件大小
  6. 在引用雪碧图的位置打上时间戳
  7. 在样式末尾追加时间戳
  8. 按照时间戳命名文件

配置说明

// 自动雪碧图
sprite: {
    options: {
        // sprite背景图源文件夹,只有匹配此路径才会处理,默认 images/slice/
        imagepath: 'test/slice/',
        // 映射CSS中背景路径,支持函数和数组,默认为 null
        imagepath_map: null,
        // 雪碧图输出目录,注意,会覆盖之前文件!默认 images/
        spritedest: 'test/publish/images/',
        // 替换后的背景路径,默认 ../images/
        spritepath: '../images/',
        // 各图片间间距,如果设置为奇数,会强制+1以保证生成的2x图片为偶数宽高,默认 0
        padding: 2,
        // 是否使用 image-set 作为2x图片实现,默认不使用
		useimageset: false,
        // 是否以时间戳为文件名生成新的雪碧图文件,如果启用请注意清理之前生成的文件,默认不生成新文件
        newsprite: false,
        // 给雪碧图追加时间戳,默认不追加
        spritestamp: true,
        // 在CSS文件末尾追加时间戳,默认不追加
        cssstamp: true,
        // 默认使用二叉树最优排列算法
        algorithm: 'binary-tree',
        // 默认使用`pixelsmith`图像处理引擎
        engine: 'pixelsmith'
    },
    autoSprite: {
        files: [{
            // 启用动态扩展
            expand: true,
            // css文件源的文件夹
            cwd: 'test/css/',
            // 匹配规则
            src: '*.css',
            // 导出css和sprite的路径地址
            dest: 'test/publish/css/',
            // 导出的css名
            ext: '.sprite.css'
        }]
    }
}
  • files

    使用标准的动态文件对象

  • options

    • imagepath 必填项,sprite背景图源文件夹,只有匹配此路径才会处理,默认 images/slice/

    • imagepath_map 映射CSS中背景路径,支持函数和数组,默认为 null

    • spritedest 必填项,雪碧图输出目录,注意,会覆盖之前文件!默认 images/

    • spritepath 可选项,替换后的背景路径,默认为 path.relative(cssDestPath, spriteDestPath);

    • padding 可选项,指定各图片间间距,默认 0

    • useimageset 可选项,是否使用 image-set 作为2x图片实现,默认不使用

    • newsprite 可选项,是否以时间戳为文件名生成新的雪碧图文件,如果启用请注意清理之前生成的文件,默认不生成新文件

    • spritestamp 可选项,是否给雪碧图追加时间戳,默认不追加

    • cssstamp 可选项,是否在CSS文件末尾追加时间戳,默认不追加

    • engine 可选项,指定图像处理引擎,默认选择pngsmith

    • algorithm 可选项,指定排列方式,有top-down (从上至下), left-right(从左至右), diagonal(从左上至右下), alt-diagonal (从左下至右上)和 binary-tree(二叉树排列) 五种供选择,默认 binary-tree;参考 Layout

载入插件

请不要忘了载入插件

grunt.loadNpmTasks('grunt-css-sprite');

打个比方

有一个类似这样的目录结构:

├── test/
    ├── css/
        └── icon.css
    ├── images/
        ├── slice/
            ├── icon-a.png
            ├── icon-a@2x.png
            ├── icon-b.png
            └── icon-b@2x.png
    └── publish/
        ├── css/
            └── icon.sprite.css
        └── images/
            ├── icon.png
            └── icon@2x.png

css/icon.css 调用images/slice/目录下的切片,grunt-css-sprite 会将 css/icon.css 进行处理。

publish/css/ 目录下是处理完成的样式 icon.sprite.css ,而 publish/images/ 目录下是合并完成的雪碧图。

特别注意

  1. 生成后的雪碧图将以源 css 文件名来命名
  2. 仅当CSS中定义url(xxxx)的路径匹配参数imagepath才进行处理,和具体backgroundbackground-imageCSS无关,这里有区别于grunt-sprite
  3. 理论上高清切片都应该是源切片尺寸的2倍,所以所有高清切片的尺寸宽和高都必须是偶数
  4. 理论上所有的切片都应该是 .png 格式,png8 png24png32不限
  5. spritesmith 默认只支持png格式,如果有其他格式需要,请参考 可选依赖

可选依赖

grunt-css-sprite 使用 spritesmith 作为内部核心实现

Mark 提醒,之前对于gm 的依赖纯属多余;如果你需要将图片处理引擎切换为gm或者其他引擎,请手动安装对应的依赖包。 举例 Graphics Magick(gm) 依赖的安装流程:

  • Graphics Magick(gm)

    • Mac // 安装GM图形库

      brew install GraphicsMagick
      npm install gmsmith
      
    • Windows 前往官方网站下载安装GM图形库 然后命令行执行:

      npm install gmsmith
      

版本记录

0.0.1grunt-sprite 迁移改进

0.0.2 完善部分处理流程,优化图片重复,规避 a[href*='}{']::after{ content:'}{';} 这类奇葩CSS

0.0.5 修改 spritesmith 依赖为 0.18.0,实现padding参数;优化Retina处理流程,拼合选择器,减小CSS文件体积 .a,.b,.c{ background-image:url(icon.png); background-size:95px auto;}

0.0.6 修正生成Retina CSS部分一个严重的逻辑错误,去除重复选择器生成;完善测试用例;添加grunt jshint任务

0.0.7 修正backgroun[-image]之后缺少分号时造成新生成的CSS出错,修改默认处理引擎为pngsmith,取消对gm的依赖

0.0.8 修正getSliceData获取所有CSS背景属性正则匹配

0.0.9 重构操作流程,添加 image-set 支持

0.1.2 添加,完善 imagepath-map 参数

0.1.3 修正 #11 #12

0.1.5 更新依赖 spritesmith 版本

0.1.6 重构整体流程,支持选择器提取,进一步优化CSS文件大小

0.2.0 分离内部逻辑,提取出 css-spritesmith,为支持 gulp 做准备

致谢

感谢 spritesmith

感谢 Meters

感谢 Mark 修正 #1,提出 #2

感谢 unmric

使用中有任何问题,请提交 Issue