joycss文档

目录导航

什么是joycss

joycss是一个基于nodejs和php的自动拼图工具。joycss的目标:使用简单,功能强大。使 用简单,就是开发者无需配置,无需为拼图本身做额外的处理。功能强大,在于可以(是可 以不是必须)随意配置,支持个性化拼图需求。

快速使用介绍:joycss使用。源码:repository

线上实例:

安装

//安装
npm install -g joycss
//最简单执行
joycss xx.css
//显示帮助信息
joycss -h

joycss目标是,让开发者无需拼图,大多数情况下,下面文档的说明不需要使用的。开发者 仅仅需要执行joycss xx.css,这样joycss会完成所有应该做的,可能存在少量的拼图错 误情况,这时候,需要单独设置图片的一些属性。单独设置主要有两种方式,命令行参数和 背景图url参数。命令行参数全局配置,url参数通常只对图片本身相关属性进行说明,比如 esc用去声明图片不加入拼图。

可能出现无法拼图的情况,整理在what-make-joycss-different一文中。

命令行使用

通过npm安装后,joycss可以终端或者shell下执行,运行joycss -h可以看到所有可以使用 的参数,在win下,dos可能出现中文乱码的情况,所有帮助文档使用英文。使用方式例子: joycss -casi example.css 表示使用close,alpha,source,important四个方式组合, 意思是,使用紧凑拼图,生成png24图片,使用.source.css文件作为输入,并且在sprite 图片后面增加!important。参数和css文件的位置可以调换,使用joycss a.css -casi也 一样,或者参数分开joycss -c a.css -a -si

-h, --help
显示帮助信息。
-v, --version
显示版本。
-y, --vertical
强制使用垂直布局。默认情况下是垂直布局和水平布局同时使用,当可以确定一个图片
所在的box的宽度的时候,使用紧凑拼图,不能确定的,独占一行,垂直布局。
-c, --close
强制使用紧凑布局。使用url参数line改变单张图片规则,使之独占一行。
-a, --alpha
生成alpha透明方式生成png24图片,默认情况使用png8,使用alpha模式的时候,同时会
生成png8图片,为ie6 兼容使用,此选项开启生成png24图作为sprite图片。
-w, --white
生成背景为白色的图片。
-s, --source
使用.source.css作为输入源。这种模式下,joycss a.css,第一次执行时,复制
a.css到a.source.css,sprite后生成文件为a.css,以后情况下,如果a.source.css存
在,则读取a.source.css作为输入文件。在默认情况下,生成文件是a.sprite.css。
-i, --important
为sprite规则增加important,提升优先级,防止被覆盖。
-u, --upload
使用图片上传。后面三个配置都是和图片上传有关,如果背景图需要使用绝对路径(在淘
宝有固定的图片cdn服务,图片上传后,返回一个http的地址),使用u参数,声明图片上
传,并且使用返回的http路径覆盖相对路径的背景图。-u模式下,会生成一个,后缀为
json 的数据文件,文件名和输入文件名相同。用于贮存上传过的图片路径,在某些情况
,样式源文件修改,背景图没有修改的情况下,不需要重新上传图片,使用下面的-n参
数,直接使用贮存在本地的图片地址。
-n, --nochange
图片没有修改,不上传图片。已经上传过背景图,使用-n参数,声明背景图本身没有修
改,无需再次上传图片,直接使用上一层上传的图片地址。
--config
上传文件接口配置,首先在某个目录下创建一个upload.json的文件,自行配置上传图片
的host和path,淘宝内部接口请使用此接口upload
然后,在当前cd到当前目录,执行joycss --config,配置文件就可以生效了。图片上
传接口必须返回json的数据,成功数据: {url: 'http://a/xx.png'},错误信息返回
{msg: 'error info'}。配置文件格式如下:
{
  "host"    : "url.com",
  "path"    : "/path/to.htm",
  "filekey" : "photo",
  "headers" : {
    "Cookie": "a=b;"
  }
}

url参数使用规则

joycss的所有与开发者交互,都是通过背景图url参数来实现的,比如

.main-right .tese h2 {
  background: url(../img/fenlei.png?id=1&way=h) repeat-y 0 0;
  width: 480px;
}

url参数指的是上面css中,background的url中那一段?id=1&way=h,表示第二组sprite 图,排列方式way为水平horizontal

参数以及对应的意义

参数名 参数全名 参数的值 意义与作用 使用实例
esc escape '' 图片无需拼图 a.png?esc
way h horizontal 排列方式水平排列 [g] a.png?way=h
way v vertical 垂直排列,默认方式[g] a.png?way=v
id id 0-9 分组id,id相同的图片合并一起 a.png?id=1
bottom bottom \d 图片设置margin bottom [v] a.png?b=10
right right \d 图片设置margin right [h] a.png?r=10
base base '' 图片放在最前面 a.png?base
end end   图片放着最后面 a.png?end
line line   图片独占一行,在close模式下 a.png?line
说明:表格中,[g]标志表示为组范围内定义,一组只需定义定一个出现的图片。[h]标 志说明,只有在水平布局[horizontal]下才有效,[v]表示只在垂直布局[vertical]有 效。其他都是针对单个图片设置的

图片分组规则

默认情况下,所有的图片分在同一个组,合成一张图片,需要额外分组,则在相应背景图图 片加上一个id=\d的参数,\d表示数字,从1开始计数,默认的sprite图片,id等于0, 不需要写

url参数的位置

url参数中,在[g]下的参数,默认情况下,是读取页面第一次出现相应图片的时候。比如

.main-left .fenlei h2 {
  background: url(../img/fenlei.png?id=1&way=h) repeat-y 0 0;
  width: 180px;
  height: 180px;
}
.main-right .tese h2 {
  background: url(../img/tese.png?id=1) no-repeat 0 10px;
  width: 480px;
}

以上css规则中,*必须*把参数way=h写在第一个选择器的背景图中,不能写在第二个图片 上面,这一点规则非常重要。

why Joycss

joycss为自动拼图而生。对于自动拼图,有几个境界,第一种,有一堆需要 sprite的图片 ,一个css文件,自动拼图工具生成一个编译后的css文件,并且合成图片。第二种,有一堆 图片,并且约定开发者,所有的图片对应一个高宽固定dom标签,拼图工具生成相应的足够 紧凑的sprite图片,并且回写css文件。如此,两者,都只是在考虑自动拼图过程,但是, 考虑到,如果使用到自动拼图,必然会有两个问题,编译后的文件和源文件切换过程。我们 可以称为开发环境和发布环境的切换,在开发环境下,编辑修改源文件,发布后,需要使用 编译后的css。

想象一下,实际使用过程中,一个css文件a.css,开发完成,然后使用自动拼图工具,完成 拼图,生成一个文件a.sprite.css,这两个文件必须同时存在,不然后续就无法维护下去了。 然后修改a.sprite.css为a.css,a.css为a.source.css,然后提交文件。如果是在淘宝,你 可能面临图片上传和css上传是分开的,需要把合成的图片a.sprite.png上传到服务器,获得 一个url,重新修改a.css,然后提交代码,发布上线。

上面的过程,自动拼图完成后,还是有很多没法自动完成的。如果需要修改a.css,过程如下:

上面描述的第二个过程,实际上是多余的。自动拼图能够做到自动拼图,但是还没有能够只 做应该做的,虽然多生成一些问题也不大,但是图片处理毕竟比较费时间,只做应该做的, 这是自动拼图工具的第三种境界。发布过程和开发环境的切换,看似不怎么重要,实际使用 中,却是非常浪费开发者时间,和对工具的兴趣。

再回到开发过程,为了做自动拼图,开发过程需要一些额外的工作,以便让自动拼图工具知 道开发这的意图,知道css中图片应该怎么拼图,那些图片需要拼图,sprite图命名,等等, 很多繁琐的事情,这个可以统称为开发者api方式。自动拼图工具通常都会有一个默认假设, 假设开发者可以接受的一种图片组合方式,简称拼图方式。最简单的拼图方式是水平或垂直 排列,复杂一些的是紧凑拼图和对角线拼图。

比如smartsprite,使用的是最简单的拼图方式,所有图片水平或垂直排列,与开发者交互, 使用的是css注释,每个需要拼图的图片都需要写注释,注释语法虽然简单,不过每次写一个 图片都写注释,还是比较麻烦的事情,学习成本也不低。拼图方式也有些不那么有好,和人工 拼图比较,难看不少。

再看看使用复杂拼图的cssgaga,使用紧凑拼图,与开发者交互是通过一个开发约定完成的 ,要求所有的图片所对于的dom大小一样,图片的大小就是对应dom元素大小,图片的名字是 dom 元素的选择器。紧凑拼图,和人工拼图比较,好看不少,不过这样的开发约定,还是有 些麻烦,距离随心所欲的境界还是差不少。此外,cssgaga跨平台性差,并且不支持命令行 方式调用,无法真正做到自动化。

那么,什么是拼图的随心所欲境界呢。首先,生成图片需要是png8格式,并且是透明的。对 发布过程支持有好,支持只编译css,保留上一次拼图结果。开发者与拼图工具的交互尽可 能简单,开发者在不做任何处理的情况下,依然可以生成sprite图。能够随意选择拼图方式, 拼图方式可以组合。

当然,上面描述可能还是有些模糊不清楚的地方,而且计算机也肯定无法做到真正的随心所 欲。 joycss所做的,是尽可能随心所欲的境界。

背景图片定位规则

背景图的位置信息,经过3个步骤的判断计算来确定的:

前面两步确定了三个方向的位置,最后一步确定最后一个方向的间距。因为拼图是垂直或水 平方式,有一个方向是无需控制的。在垂直布局下,第三步只确定底部空间高度,水平布局 ,第三步确定右边间距。

背景图repeat

repeat不能同时和定位使用,也就是,有repeat,必须是position:0 0,这样的形式。重复 的单位是重复图片的倍数,如果图片很大,可能大致图片重复以后高度宽度多出不少。默认 情况下,不写repeat属性,在css解释用,是表示图片重复,不过在大多数情况下,不写 repeat 是因为开发者懒得写,同时背景图大小和所在的div大小一致,repeat和no-repeat 意义一样,所以,joycss默认解释repeat为no-repeat,如果有 repeat的图片,将无法拼图 ,如果是repeat-x 或者repeat-y的方式,请不用省略。

sprite图片合并规则

sprite图片名是文件名加上spriteId加上-sprite组成的,比如文件a.css,拼图后生成的 图片地址是a-sprite.png, a1-sprite.png。spriteId构成是和文件名同名,如果一个css 中有多个sprite图片,那么第二个开始加上数字,数字从1开始计数。

依赖

需要nodejs和php cli支持,php需要有gd库支持。

项目中使用到的其他开源代码

非常感谢Alexander Kaupp提供的php版本 smartsprite, 如果没有这个拼图过程 的api,joycss还是在摸索如何拼图中,smartsprite提供了很好的拼图功能 ,src/graph/smartsprite.php中,把smartsprite的拼图功能独立出来,通过 src/graph/tpl.json这样的json文件作为数据源,php版的smartsprite完成图片处理过程 , node执行css分析过程。

此外,lib/PropertyValuePart.js使用了 nzakas/parser-lib 中的 src/css/PropertyValuePart.js,一个很好的css value读取代码。紧凑拼图使用了, jakesgordon/bin-packing的算法, 代码位置lib/packer.js

comments powered by Disqus