• 设为首页
  • 点击收藏
  • 手机版
    手机扫一扫访问
    迪恩网络手机版
  • 关注官方公众号
    微信扫一扫关注
    迪恩网络公众号
登陆 注册
描述文字

twolfson/gulp.spritesmith: Convert a set of images into a spritesheet and CSS va ...

原作者: [db:作者] 来自: 网络 收藏 邀请

开源软件名称（OpenSource Name）：

twolfson/gulp.spritesmith

开源软件地址(OpenSource Url)：

https://github.com/twolfson/gulp.spritesmith

开源编程语言(OpenSource Language)：

JavaScript 62.8%

开源软件介绍(OpenSource Introduction)：

gulp.spritesmith Build status Subscribe to newsletter

Convert a set of images into a spritesheet and CSS variables via gulp

This is the official port of grunt-spritesmith, the grunt equivalent of a wrapper around spritesmith.

Example input/output

Alternative output formats include SASS, Stylus, LESS, and JSON.

Retina support

As of [email protected], retina spritesheets/templates are supported. See the Retina parameters section for more information.

Do you like gulp.spritesmith?

Support us via donations or spread word on Twitter

Breaking changes in 4.0.0

We are normalizing sprite variables even further to convert any non-alphanumeric/non-dash/non-underscore character to a delimiter character (e.g. -). This allows us to support naming retina sprites with @2x suffixes, to prevent regressions like grunt-spritesmith#137.

Breaking changes in 5.0.0

We have moved from [email protected] to [email protected]. This means if you use an custom engine (e.g. gmsmith, canvassmith), then you will need to upgrade it.

npm install my-engine-smith@latest --save-dev

This is enables us to use streaming outputs from engines in a future release.

Additionally, we have added support for buffer and stream content for in-memory engines (e.g. pixelsmith, canvassmith) which resolves #53.

Breaking changes in 6.0.0

We have completed our integration with streaming outputs from engines. As a result, Vinyl img files will have stream contents which were previously buffers.

If your img pipeline requires Buffer contents, then this can be remedied via vinyl-buffer:

// Throws error due to not supporting streams
spriteData.img.pipe(imagemin());

// Back to operational
var buffer = require('vinyl-buffer');
spriteData.img.pipe(buffer()).pipe(imagemin());

Getting Started

Install the module with: npm install gulp.spritesmith

var gulp = require('gulp');
var spritesmith = require('gulp.spritesmith');

gulp.task('sprite', function () {
  var spriteData = gulp.src('images/*.png').pipe(spritesmith({
    imgName: 'sprite.png',
    cssName: 'sprite.css'
  }));
  return spriteData.pipe(gulp.dest('path/to/output/'));
});

Continuing the pipeline

In addition to the spriteData stream, we offer individual streams for images and CSS. This allows for image optimization and CSS minification.

var gulp = require('gulp');
var buffer = require('vinyl-buffer');
var csso = require('gulp-csso');
var imagemin = require('gulp-imagemin');
var merge = require('merge-stream');

var spritesmith = require('gulp.spritesmith');

gulp.task('sprite', function () {
  // Generate our spritesheet
  var spriteData = gulp.src('images/*.png').pipe(spritesmith({
    imgName: 'sprite.png',
    cssName: 'sprite.css'
  }));

  // Pipe image stream through image optimizer and onto disk
  var imgStream = spriteData.img
    // DEV: We must buffer our stream into a Buffer for `imagemin`
    .pipe(buffer())
    .pipe(imagemin())
    .pipe(gulp.dest('path/to/image/folder/'));

  // Pipe CSS stream through CSS optimizer and onto disk
  var cssStream = spriteData.css
    .pipe(csso())
    .pipe(gulp.dest('path/to/css/folder/'));

  // Return a merged stream to handle both `end` events
  return merge(imgStream, cssStream);
});

Documentation

gulp.spritesmith presents the spritesmith function as its module.exports.

spritesmith(params)

gulp plugin that returns a transform stream with 2 readable stream properties.

The input/output streams interact with Vinyl objects which are gulp's format of choice.

  • params Object - Container for gulp.spritesmith parameters
    • imgName String - Filename to save image as
      • Supported image extensions are .png and .jpg/jpeg (limited to specfic engines)
      • Image format can be overridden via imgOpts.format
    • cssName String - Filename to save CSS as
      • Supported CSS extensions are .css (CSS), .sass (SASS), .scss (SCSS), .less (LESS), .styl/.stylus (Stylus), and .json (JSON)
      • CSS format can be overridden via cssFormat
    • imgPath String - Optional path to use in CSS referring to image location
    • padding Number - Optional amount of pixels to include between images
      • By default we use no padding between images (0)
      • An example usage can be found in the Examples section
    • algorithm String - Optional method for how to pack images
      • By default we use binary-tree, which packs images as efficiently as possible
      • An example usage can be found in the Examples section
      • More information can be found in the Algorithms section
    • algorithmOpts Object - Options to pass through to algorithm
      • For example we can skip sorting in some algorithms via {algorithmOpts: {sort: false}}
        • This is useful for sprite animations
      • See your algorithm's documentation for available options
    • engine String - Optional image generating engine to use
      • By default we use pixelsmith, a node based engine that supports all common image formats
      • Alternative engines must be installed via npm install
      • An example usage can be found in the Examples section
      • More information can be found in the Engines section
    • engineOpts Object - Options to pass through to engine for settings
      • For example phantomjssmith accepts timeout via {engineOpts: {timeout: 10000}}
      • See your engine's documentation for available options
    • imgOpts Object - Options to pass through to engine uring export
      • For example gmsmith supports quality via {imgOpts: {quality: 75}}
      • See your engine's documentation for available options
    • cssFormat String - CSS format to use
    • cssTemplate String|Function - CSS template to use for rendering output CSS
      • This overrides cssFormat
      • If a String is provided, it must be a path to a handlebars template
      • If a Function is provided, it must have a signature of function (data)
      • For more templating information, see the Templating section
    • cssHandlebarsHelpers Object - Container for helpers to register to handlebars for our template
      • Each key-value pair is the name of a handlebars helper corresponding to its function
      • For example, {half: function (num) { return num/2; } will add a handlebars helper that halves numbers
    • cssVarMap Function - Mapping function for each filename to CSS variable
    • cssSpritesheetName String - Name to use for spritesheet related variables in preprocessor templates
    • cssOpts Object - Options to pass through to templater

Returns:

Retina parameters

gulp.spritesmith supports retina spritesheet generation via retinaSrcFilter and retinaImgName. If at least one of these is provided, then we will expect the other and enable retina spritesheet generation.

Repeated parameters have the same properties as above but are repeated for clarity with respect to retina spritesheets.

An example retina spritesheet setup can be found in the Examples section.

We receive both normal and retina sprites from the same gulp.src so please include them in your original glob. (e.g. *.png should include icon-home.png and [email protected]).

We strongly encourage using the @2x suffix for retina sprites over -retina or -2x. There are known ordering issues caused when sharing a - delimiter between sprite names and the retina suffix (see grunt-spritesmith#137).

  • params Object - Container for gulp.spritesmith parameters
    • retinaSrcFilter String|String[] - Filepaths to filter out from incoming stream for our retina spritesheet
      • This can be a glob as with src (e.g. sprite/*@2x.png)
      • The path/glob used should line up with gulp.src (e.g. gulp.src('sprite/*.png'), retinaSrcFilter: 'sprite/*@2x.png')
      • For example sprites/*@2x.png will filter out [email protected] for a separate retina spritesheet
        • Under the hood, we will group sprite1.png and [email protected] as a group of normal/retina sprites
    • retinaImgName String - Filename to save retina spritesheet as
    • retinaImgPath String - Optional path to use in CSS referring to image location
    • padding Number - Padding to place to right and bottom between sprites
      • By default there is no padding
      • In retina spritesheets, this number will be doubled to maintain perspective
    • cssFormat - CSS format to use
    • cssVarMap Function - Mapping function for each filename to CSS variable
      • This will run through normal and retina spritesheets
      • The name used for normal sprites dictates the group name for retina group variables (e.g. $icon-home will have group $icon-home-group)
      • For more information, see Variable mapping
    • cssRetinaSpritesheetName String - Name to use for retina spritesheet related variables in preprocessor templates
    • cssRetinaGroupsName String - Name to use for retina groups related variables in preprocessor templates

Returns:

  • spriteData stream.Transform - Stream that outputs image, retina image, and CSS as Vinyl objects
  • spriteData.img stream.Readable - Stream for image outputs (normal and retina) as a Vinyl object
    • contents will be a Stream
  • spriteData.css stream.Readable - Stream for retina CSS output as a Vinyl object
    • contents will be a Buffer

Algorithms

Images can be laid out in different fashions depending on the algorithm. We use layout to provide you as many options as possible. At the time of writing, here are your options for algorithm:

top-down left-right diagonal alt-diagonal binary-tree
top-down left-right diagonal alt-diagonal binary-tree

More information can be found in the layout documentation:

https://github.com/twolfson/layout

Templating

The cssTemplate option allows for using a custom template. An example template can be found at:

https://github.com/twolfson/spritesheet-templates/blob/9.3.1/lib/templates/stylus.template.handlebars

The parameters passed into your template are known as data. We add some normalized properties via spritesheet-templates for your convenience.

  • data Object Container for parameters
    • sprites Object[] - Array of sprite information
      • name String - Name of the sprite file (sans extension)
      • x Number - Horizontal position of sprite's left edge in spritesheet
      • y Number - Vertical position of sprite's top edge in spritesheet
      • width Number - Width of sprite
      • height Number - Height of sprite
      • total_width Number - Width of entire spritesheet
      • total_height Number - Height of entire spritesheet
      • image String - Relative URL path from CSS to spritesheet
      • escaped_image String - URL encoded image
      • source_image String - Path to the original sprite file
      • offset_x Number - Negative value of x. Useful to background-position
      • offset_y Number - Negative value of y. Useful to background-position
      • px Object - Container for numeric values including px
        • x String - x suffixed with px
        • y String - y suffixed with px
        • width String - width suffixed with px
        • height String - height suffixed with px
        • total_width String - total_width suffixed with px
        • total_height String - total_height suffixed with px
        • offset_x String - offset_x suffixed with px
        • offset_y String - offset_y suffixed with px
    • spritesheet Object - Information about spritesheet
      • width Number - Width of entire spritesheet
      • total_height Number - Height of entire spritesheet
      • image String - Relative URL path from CSS to spritesheet
      • escaped_image String - URL encoded image
      • px Object - Container for numeric values including px
        • width String - width suffixed with px
        • height String - height suffixed with px
    • spritesheet_info Object - Container for spritesheet metadata and its representation
      • name String - Prefix for spritesheet variables
    • retina_sprites Object[] - Array of retina sprite information
      • This will only be accessible if we are generating a retina spritesheet
      • Properties are the same as sprites (e.g. name, width, source_image)
    • retina_spritesheet Object - Information about retina spritesheet
      • This will only be accessible if we are generating a retina spritesheet
      • Properties are the same as spritesheet (e.g. width, px)
    • retina_spritesheet_info Object - Container for retina_spritesheet metadata and its representation
      • This will only be accessible if we are generating a retina spritesheet
      • name String - Prefix for spritesheet variables
    • retina_groups Object[] - Array of objects that maps to normal and retina sprites
      • This will only be accessible if we are generating a retina spritesheet
        • Object - Container for data about sprite mapping
          • name String - Name to refer to mapping by
          • index Number - Index of corresponding normal/retina sprites from data.sprites/data.retina_sprites
          • normal Object - Normal sprite from data.sprites that corresponds to our mapping
            • This has all the same properties as data.sprites[*] (e.g. name, x, offset_y, px)
          • retina Object - Retina sprite from data.retina_sprites that corresponds to our mapping
            • This has all the same properties as data.retina_sprites[*] (e.g. name, x, offset_y, px)
    • retina_groups_info Object - Optional container for metadata about retina_groups and its representation
      • This will only be accessible if we are generating a retina spritesheet
      • name String - Name for retina_groups
    • options Object - Options passed in via cssOpts in gulp.spritesmith config

An example sprite is

{
  "name": "sprite2",
  "x": 10,
  "y": 20,
  "width": 20,
  "height": 30,
  "total_width": 80,
  "total_height": 100,
  "image": "nested/dir/spritesheet.png",
  "escaped_image": "nested/dir/spritesheet.png",
  "source_image": "path/to/original/sprite.png",
  "offset_x": -10,
  "offset_y": -20,
  "px": {
    "x": "10px",
    "y": "20px",
    "width": "20px",
    "height": "30px",
    "total_width": "80px",
    "total_height": "100px",
    "offset_x": "-10px",
    "offset_y": "-20px"
  }
}

If you are defining a Handlebars template, then you can inherit from an existing template via handlebars-layouts (e.g. {{#extend "scss"}}). An example usage can be found in the Examples section.

Example usages can be found as:

Variable mapping

The cssVarMap option allows customization of the CSS variable names

If you would like to customize CSS selectors in the css template, please see https://github.com/twolfson/spritesheet-templates#css

Your cssVarMap should be a function with the signature function (sprite). It will receive the same parameters as sprites from Templating except for escaped_image, offset_x, offset_y, and px.

// Prefix all sprite names with `sprite-` (e.g. `home` -> `sprite-home`)
cssVarMap: function (sprite) {
  sprite.name = 'sprite_' + sprite.name;
}

// Generates:
// $sprite_fork_x = 0px;
// $sprite_fork_y = 0px;

// As oppposed to default:
// $fork_x = 0px;
// $fork_y = 0px;

Engines

An engine can greatly improve the speed of your build (e.g. canvassmith) or support obscure image formats (e.g. gmsmith).

All spritesmith engines adhere to a common specification:

https://github.com/twolfson/spritesmith-engine-spec

This repository adheres to specification version: 2.0.0

Below is a list of known engines with their tradeoffs:

pixelsmith

pixelsmith is a node based engine that runs on top of get-pixels and save-pixels.

Key differences: Doesn't support uncommon image formats (e.g. tiff) and not as fast as a compiled library (e.g. canvassmith).

phantomjssmith

phantomjssmith is a phantomjs based engine. It was originally built to provide cross-platform compatibility but has since been succeeded by pixelsmith.

Requirements: phantomjs must be installed on your machine and on your PATH environment variable. Visit the phantomjs website for installation instructions.

Key differences: phantomjs is cross-platform and supports all image formats.

canvassmith

canvassmith is a node-canvas based engine that runs on top of Cairo.

Requirements: Cairo and node-gyp must be installed on your machine.

Instructions on how to install Cairo are provided in the node-canvas wiki.

node-gyp should be installed via npm:

npm install -g node-gyp

Key differences: canvas has the best performance (useful for over 100 sprites). However, it is UNIX only.

gmsmith

gmsmith is a gm based engine that runs on top of either Graphics Magick or Image Magick.

Requirements: Either Graphics Magick or Image Magick must be installed on your machine.

For the best results, install from the site rather than through a package manager (e.g. apt-get). This avoids potential transparency issues which have been reported.

Image Magick is implicitly discovered. However, you can explicitly use it via engineOpts

{
  engineOpts: {
    imagemagick: true
  }
}

Key differences: gmsmith allows for configuring image quality whereas others do not.

Examples

Algorithm

In this example, we are using the alt-diagonal algorithm to guarantee no overlap if images overflow.

Configuration:

{
  imgName: 'sprite.png',
  cssName: 'sprite.styl',
  algorithm: 'alt-diagonal'
}

Output:

algorithm spritesheet

Engine

In this example, we are using the phantomjssmith engine as an alternative to the pixelsmith default.

Requirements:

Install phantomjssmith to our node_modules via npm install.

npm install phantomjssmith

Alternatively, we can use --save or --save-dev to save to our package.json's dependencies or devDependenices.

npm install phantomjssmith --save  # Updates {"dependencies": {"phantomjssmith": "1.2.3"}}
npm install phantomjssmith --save-dev  # Updates {"devDependencies": {"phantomjssmith": "1.2.3"}}

Configuration:

// var phantomjssmith = require('phantomjssmith');
{
  imgName: 'sprite.png',
  cssName: 'sprite.styl',
  engine: phantomjssmith
}

Output:

engine spritesheet

Padding

The padding option allows for inserting spacing between images.

Configuration:

{
  imgName: 'sprite.png',
  cssName: 'sprite.styl',
  padding: 20 // Exaggerated for visibility, normal usage is 1 or 2
}

Output:

该文章已有0人参与评论

请发表评论

全部评论

专题导读
More+
上一篇：
targetkiller/gulp-imageisux: 智图gulp插件发布时间：2022-06-21
下一篇：
klei/gulp-inject: A javascript, stylesheet and webcomponent injection plugin for ...发布时间：2022-06-21
热门推荐
More+
热门话题
More+
阅读排行榜

扫描微信二维码

查看手机版网站

随时了解更新最新资讯

139-2527-9053

在线客服（服务时间 9:00～18:00）

在线QQ客服
地址：深圳市南山区西丽大学城创智工业园
电邮：jeky_zhao#qq.com
移动电话：139-2527-9053

Powered by 互联科技 X3.4© 2001-2213 极客世界.|Sitemap