node-sprite uses ImageMagick for its graphics operations. So make sure you have the convert and identify command available in your envirnoment.
There are three exported functions: sprite, sprites and stylus. The following examples show how to use them.
- app.js
- images/
- global/
- bar.jpg // 200x100px image
- foo.png // 10x50px image
- animals/
- cat.gif // 64x64px image
- duck.png // 64x64px image
- mouse.gif // 64x64px image
var sprite = require('node-sprite');
sprite.sprite('global', {path: './images'}, function(err, globalSprite) {
console.log(globalSprite.filename())
console.log('foo', globalSprite.image('foo'));
console.log('bar', globalSprite.image('bar'));
});This code will generate a sprite image named ./images/global-[checksum].png and output the following:
global-45c81.png
foo, {width: 200, height: 100, positionX: 0, positionY: 52}
bar, {width: 64, height: 64, positionX: 0, positionY: 0}
var sprite = require('node-sprite');
sprite.sprites({path: './images'}, function(err, result) {
var globalSprite = result['global'];
var animalsSprite = result['animals'];
console.log(globalSprite.filename());
console.log(animalsSprite.filename());
console.log('animals/duck', animalsSprite.image('duck'));
});This code will generate a sprite image for every subfolder of ./images. The images are named ./images/[folder]-[checksum].png.
global-45c81.png
animals-b775d.png
animals/duck, {width: 10, height: 50, positionX: 0, positionY: 66}
// screen.styl
#duck
sprite animal duck
#mouse
sprite global mouse false
The sprite function generates the correct background image and position for the specified image. By default it also adds width and height properties. You can prevent this behaviour by setting the third optional parameter to false.
/* screen.css */
#duck {
background: url('./images/animals-b775d.png') 0px -66px;
width: 64px;
height: 64px;
}
#mouse {
background: url('./images/animals-b775d.png') 0px -132px;
}The sprite.stylus function behaves similar to sprite.sprites, but it returns a helper object, with provides a stylus helper function helper.fn.
var sprite = require('node-sprite');
var stylus = require('stylus');
var str = require("fs").readFileSync("screen.styl")
sprite.stylus({path: './images'}, function (err, helper) {
stylus(str)
.set('filename', 'screen.styl')
.define('sprite', helper.fn)
.render(function (err, css) {
console.log(css);
});
});node-sprite has a special mode for high resolution sprites. When your sprite folder ends with @2x it will be treated differently.
animals@2x/
- cat.gif // 128x128px image
- duck.png // 128x128px image
Although we have 128x128px images. The elements should only have the size of 64x64px and the background has to be scaled down.
// screen.styl
#duck
sprite(animal@2x, duck)
background-size sprite-dimensions(animal@2x, name)
will be transformed to
/* screen.css */
#duck {
background: url('./images/[email protected]') 0px -66px;
width: 64px;
height: 64px;
background-size: 64px 194px;
}For this to work you have to add the sprite-dimensions helper in you stylus configuration:
.define('sprite-dimensions', helper.dimensionsFn)
If you want to have a retina and a non-retina sprite it makes sense to create a mixin like this one:
// screen.styl
retina-sprite(folder, name)
sprite(folder, name)
hidpi = s("(min--moz-device-pixel-ratio: 1.5), (-o-min-device-pixel-ratio: 3/2), (-webkit-min-device-pixel-ratio: 1.5), (min-resolution: 1.5dppx)");
@media hidpi
sprite(folder+"@2x", name, false)
background-size sprite-dimensions(folder+"@2x", name)
#duck
retina-sprite animals duck
This will generate the following css code:
#duck {
background: url('./images/animals-b775d.png') 0px -66px;
width: 64px;
height: 64px;
}
@media (min--moz-device-pixel-ratio: 1.5), (-o-min-device-pixel-ratio: 3/2), (-webkit-min-device-pixel-ratio: 1.5), (min-resolution: 1.5dppx) {
#duck {
background: url('./images/[email protected]') 0px -66px;
background-size: 64px 194px;
}
}Note: All images in the retina folder should have even height and width pixels.
All three functions accept an optional options parameter.
{
path: './images', // sprite directory
padding: 2, // pixels between images
httpPath: './images', // used be the stylus helper
watch: false, // auto update sprite in background
retina: '@2x' // postfix for retina sprite folders
}If you pass watch: true as an option node-sprite will watch the sprite folders and regenerate the sprite when something changes.
You can subscribe to the update event of the sprite or helper object to get notified.
var generateCss = function () {...};
sprite.stylus({watch: true}, function (err, helper) {
generateCss();
helper.on("update", generateCss);
});node-sprite will put a ./images/[folder].json next to every generated sprite image. This file contains structural information of the generated sprite. This files can be used by other modules or applications.
They are also usefull if you running your application on a production machine without ImageMagick. In this case node-sprite will fallback to this data.
{
"name": "animals",
"checksum": "b775d6fa89ad809d7700c32b491c50f0",
"shortsum": "b775d",
"images": [
{
"name": "cat",
"filename": "cat.gif",
"checksum": "25ce6895f8ed03aa127123430997bbdf",
"width": 64,
"height": 64,
"positionX": 0,
"positionY": 0
},
...
]
}Feel free to post issues or pull request.
You can run the projects tests with the npm test command.
The MIT License
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent