Compass中文开发规范手册

开始

compass目前已经不再维护，但我仔细看了下，规范和开发方式，仍值得学习，目前只翻译规范，具体的api占时不计划翻译。

Version: 1.0.1

开始使用Compass

Compass 是一款使用Sass语言 编写的开源的css设计框架，使用
起来强大和简单. 如果你对Sass不熟悉, 可以去sass-lang.com学习如何使用.

安装Compass

请按照Compass 安装指南按步骤安装Compass和Sass。

如果需要验证版本，可以运行以下命令:

$ compass version

监视和编译你的项目

（ps：watch参数就是，监控你的项目是否则有文件改动，一旦有改动，就自动转成css。）

当开发项目时, 你可以运行compass监视器 ，自动修改你的css文件到最新状态。

$ cd /path/to/project
$ compass watch

当在生产环境中编译你的css文件的时, 通过 –production 编译器将默认对终端(就是我们用的浏览器)优化输出(其实就是精简):

$ compass compile --production

使用Compass不用命令行

你可以不用compass命令行. 在一些情况下, 对于一些不是明确支持Compasssass编译器和框架，这样更容易集成.

$ gem install compass-core
$ cat <<- EOF > _project-setup.scss
\$project-path: absolute-path(join-file-segments(".."));
@import "compass/configuration";
\$compass-options: (http_path: "/");
@include compass-configuration(\$compass-options);
EOF
Add to the top of each sass file: @import "project-setup";
Compile using the Sass command line:
$ sass -r compass-core --update sass:css

详情请读: Compass’s Sass-based配置选项.

更多配置命令

所有compass命令的文档可以通过运行下面的代码发现:

$ compass help

可以设置一个可选参数，指定具体的一个命令:

$ compass help <command>

就是指定的命令参数 (例如. compile)

教程

教程

Compass 教程

这个教程还在改进, 如果这里还有什么教程没有涉及到，请看 Compass 联络表， 那里有很多compass大神帮你解决。

Compass入门

如果你对Compass不熟悉, 你最好看看 最佳练习, 配置参照, 变量配置, 还有 命令行手册.

贡献点?

如果你使用Compass中有些建议和想法, 可以看下贡献 和 创建插件.

应用集成

应用集成

Ruby on Rails

Rails 3.1（一款构建在 Ruby 语言之上的一款web框架）

添加compass到你的依赖中:

gem 'compass'

也可以去 gist(一款代码分享平台)看看

Rails 3

compass init rails /path/to/myrailsproject

Rails 2.3

rake rails:template LOCATION=http://compass-style.org/rails/installer

Sinatra

Sinatra （基于ruby的微型web框架）

require 'compass'
require 'sinatra'
require 'haml'

configure do
  set :haml, {:format => :html5}
  set :scss, {:style => :compact, :debug_info => false}
  Compass.add_project_configuration(File.join(settings.root, 'config', 'compass.rb'))
end

get '/stylesheets/:name.css' do
  content_type 'text/css', :charset => 'utf-8'
  scss :"stylesheets/#{params[:name]}", Compass.sass_engine_options
end

get '/' do
  haml :index
end

假设你保存配置文件到 config/compass.rb. 如果你保存样式表到 “views/stylesheets/” 目录，而不是 “views/”, 记得按你设置好的配置更新 sass_dir . 看看 sample compass-sinatra project 实时运行!

Sinatra Bootstrap - 一个 支持Haml, Sass, Compass, jQuery 等 的Sinatra项目.

nanoc

nanoc 是一个用 Ruby 实现的静态网页产生工具

最小集成: 只需要拖他进去

最简单的途径集成compass到nanoc. 更改 config.rb 指向到你所使用的样式表. 你需要单独运行一个窗口用Compass watch命令监控编译nanoc程序.

实力项目，如: unthinkingly.

标准集成

Nanoc文件规范的首要要点, 像这样加载 Compass 配置文件:

require 'compass'

Compass.add_project_configuration 'compass.rb'# when using Compass > 0.10
sass_options = Compass.sass_engine_options# when using Compass > 0.10

Compass.configuration.parse 'compass.rb'  when using Compass < 0.10
sass_options = Compass.config.to_sass_engine_options  when using Compass < 0.10

创建并配置一个 compass.rb 文件到你站点的根目录 .示例配置:

http_path = "/"
project_path = File.expand_path(File.join(File.dirname(__FILE__), '..'))
css_dir = "output/stylesheets"
sass_dir = "content/stylesheets"
images_dir = "assets/images"
javascripts_dir = "assets/javascripts"
fonts_dir = "assets/fonts"
http_javascripts_dir = "javascripts"
http_stylesheets_dir = "stylesheets"
http_images_dir = "images"
http_fonts_dir = "fonts"

根据您的目录结构和配置，您可能需要更改一些目录的路径。

Sass 和 Compass过滤样式表, 从Compass按照配置好的sass引擎，调用sass进行过滤, 如下:

    compile '/stylesheets/*' do
      filter :sass, sass_options.merge(:syntax => item[:extension].to_sym)
    end

    nanoc projects using the formal approach

站点

最佳方法

按下面的方法可以使你的项目更以维护和创建.

使用一个Base样式表文件

创建一个_base.scss partial(部分) 用来初始化样式表中共同的变量和集成一些你经常使用的工具。

_base.scss

$blueprint-grid-columns : 24;
$blueprint-grid-width   : 30px;
$blueprint-grid-margin  : 10px;
$font-color             :333;

@import "compass/reset";
@import "compass/utilities";
@import "blueprint";

// etc.
_base.scss 同时也是储存你自定义 mixins(混合)的好地方, 所以它可以供任何样式表用。

你可以在其他样式表中包含它:

application.scss

@import "base";

#wrapper {
  @include container;
}

// etc.
如果你想覆盖掉base.scss,可以在@import-ing之前，定义一些compass/framework 常量. 请参见可配置的变量里具体的例子. 请注意，您可以参考 base.scss的，因为它是局部的,所以名字没有前置下划线和扩展名。(译者注:这里意思就是partial是公共部分，不属于私有，所以起名字的时候不要加或者扩展名)

编写自定义Mixins

Mixins让你通过一条命令就可以把多个样式表插入选择器. 这样可以使你的源码避免重复，提升可维护性. 使用mixins让你的样式表源码像自己注释的文档 – 这样更易读，例如 @include round-corners(6px,f00) 要比列出多条语句强很多。

自由标记样式表

从一个站点的页面中提取出我们所关注的css样式. 这样看似更易于维护. 然而, 事实上, 由于CSS功能上的限制抽象成符合DRY原则的可维护的代码. 不过sass它能让我们能够创建完全抽象和重用的代码，允许我们把所有的样式移入到样式表里。 读这篇博客关于这个问题的更多信息

一旦你有整洁的标记，使用mixin和继承的样式表。整洁清晰的抽象，您应该能够阅读网页的样式表,甚至没有在Web浏览器中加载该页,就想象出页面会是什么样子。

如果你发现语义化的选择器使得你的css表臃肿，是时候到重构的时间了，例如，此样式表将产生不必要的膨胀:

@mixin three-column {
  .container { @include container;  }
  .header,
  .footer    { @include column(24); }
  .sidebar   { @include column(6);  }
  article    { @include column(10); }
  .rightbar  { @include column(8);  }
}
body#article,
body#snippet,
body#blog-post { @include three-column; }

相反的，问问自己，“这些页面非样式的实质共同点是什么？”在这种情况下，他们的所有内容页面，最好把这些页面的body类单独编辑。(译者注，上面的sass样式表，编写完很臃肿冗余的。这把所有页面的内容都合并在了一起。产生太多没必要的语句。所以为了省代码，不如单独写更易于维护)

嵌套选择器不要太多层。

从零开始进行样式处理或以应用程序的一些常见的基点，要比应付不想要的风格到您的新设计的容易多。这样，在标记书中使用一些选择器，最好使用一些基本嵌套样式。然后使用重构模式的出现，减少膨胀。

重要的是过长嵌套的选择器会导致一个小渲染的性能损失，可以减缓您的Web页面。没有必要完全模仿你的css文档结构。嵌套只有足够深的选择器是唯一的部分。例如，不要使用table thead tr th，当一个简单th选择器时就足够了。这可能意味着你必须把你的风格分成若干选择器，让文档级联工作。

促进

促进Compass发展

感谢您有兴趣在促进compass发展。我们因你而变，如果这里有难以懂的地方，请让我们知道。
如果你发现文档中的错误，可以按步骤告知我们

Step 1: 去github上注册个账号.

Step 2: 用你的账户Fork Compass.

简单改进

感谢gihub让我们的迭代更加加单. 克隆镜像到本地，commit你的项目。

编辑文档

compass文档存在两个地方. 一个在compass-style.org directory
但大部分Sass中的注释生成文档文件本身。一个在github。

修复Bugs

Step 3: 如果发现bug请及时bug，以便我们更新

Step 4: 如果你不知道如如何提交。点 the code

Step 5: 修复bug推送进度. 请务必提到的bug ID在您的提交消息，像这样:

Fixed the display of the fizzlebuzz in IE6.

Closes GH-123.

Step 6: 尽可能在多个浏览器上测试

Step 7: 确保测试通过. 完善测试

可以提交代码了

更改样式表

如果你有什么好想法，别害羞发给我哈。

许多特征的想法很好，非常适合compass核心库。在这些情况下，
你可以创建一个罗盘的扩展。有时这是因为compass的哲学概念不合。有时这只是因为我们认为这个想法需要时间考验。。
Step 3: 如果你不知道如如何提交

Step 4: 点添加特性.

Step 5: 写测试发给我们.

Step 6: 编写文档实例给我们

结束

更改ruby

如果你是对Ruby的规划工作方面的事情，假设你知道怎么读的代码，并使用标准Ruby工具，例如rake, gem, bundler, test/unit, cucumber, rspec,等。如果您有任何问题，请询问。问题随着解决。

补丁提交

如果你有多个功能要提交，请创建一个主分支，然后合并，迭代更新。
创建一个主分支:
$ git checkout -b new_branch_name
… 可以commit一下 …
$ git push origin new_branch_name
你可以看到url的改变:

http://github.com/your_user_name/compass/commits/new_branch_name

如果你有单提交的补丁，保存到master分支。但请记住，这些变更可能被刻意地挑选出来。
一旦你的变更GitHub上，确保你针对选择上游分支开发，选择包含您的更改适当的分支并发送一个pull请求。。大部分的描述应该在commit信息中–因此，没有必要写一大堆在请求消息。

Pull 请求实例

简单说Pull请求就是从fork到merge的整个过程

像compass页面的pull request由管理问题托管。代码审查由compass的核心团队成员维护:

更新被拒绝 – 更新不符合compass规范. 如果你的修改更好, 至少等到他已经到期，或者用户认可。
更新被拒绝, 除非 – 有时,有丢失的部分，或其他的变化需要作出的更改。建议指出要解决的问题
更新统一 – 更新合并到compass, 小的改动由提交者合并后提交。

项目结构

compass/
  core/                     - compass配置和样式核心文件.
    frameworks/             - 该目录框架自动加载。
      compass/              - compass框架
        stylesheets/        - compass库
        templates/          - compass模板和模式
    test/                   - 单元测试
    lib/
      compass-core.rb       - compass-core ruby 库
      compass/
        core/
          sass_extensions/  - 增强 Sass
            functions/      - Sass函数 
            monkey_patches/ - sass 更改
        configuration/      - 支持的项目配置
  cli/                      - compass命令行
    bin/
      compass               - CLI 可执行文件
    devbin/                 - 安装包后的脚本文件
    test/                   - 单元测试
    features/               - compass测试
    lib/
      compass.rb            - compass-core ruby 库
      compass/
        app_integration/    - 集成app框架
        commands/           - UI 不支持命令
        configuration/      - 一些特殊的命令
        exec/               - UI 命令
        installers/         - 安装模板支持
  compass-style.org/        - 文档源码
    output/                 - 生成文档
  import-once/              - 引入Compass

一般哲学(其实就是规范)

1.用户可以指定选择器。compass永远不会强制用户使用一个样式的类名。

2.Compass 不需要javascript

3.compass核心与设计无关。这就是为什么compass没有栅格系统，因为栅格系统和设计有关。

4.compass并不特别，compass能做的，扩展也能做。
5.Sass非常棒 – compass使Sass更容易，并证明如何使用Sass充分发挥其潜力。.
6.浏览器的兼容很头疼。需要共同解决。
7.默认情况下，compass支持尽可能多的浏览器，渐进增强，向后兼容。

8.compass是一个Sass的试验场。watcher和 color function的例子转移到sass。

样式约定

1.框架所有的样式都是(私有)部分. 它们由一个下划线开始. 否则, Sass 将直接在用户的css目录创建样式表
2.Compass不引入额外样式. 也有例外如 resets 和 集成的基类。
3.Mixins 提供两个级别的默认设置
. 第一是一个全局默认，可以重写一次
. 第二个默认mixin如果包含进来，可以重写.
4.Mixin 参数名称的公共API部分
,确保易懂，不要简短.
5.创建一个新的文件夹放样式表, 用一个和文件夹名一样的样式表导入所有的样式表 .
6.尽量避免通过选择器作为参数。

常见问题 &杂项信息

设置Git

请按照以下这些指示来设置您的电子邮件地址和属性的信息。.

下载git repo:

git clone git@github.com:your_username/compass.git

链接远程 repo:

cd compass
git remote add chriseppstein git://github.com/chriseppstein/compass.git

获取最近更新:

git fetch chriseppstein

在开发中使用compass

使用本地脚本可以放在 /path/to/compass/bin/compass 。 你可以添加 /path/to/compass/bin 到$PATH(环境变量), 或者选择其他目录.
创建安装gem:
编辑 VERSION 改变 version像这样: 1.0.0.something-unique-to-me.0

gem build compass.gemspec
gem install compass-0.10.6.something-uniq-to-me.0.gem

– 如果安装gems到你的系统, 你可能需要用 sudo . 如果你不明白什么意思，就加上它(sudo意思就是superuser
do 的缩写)
捆绑环境, 你可以像这样用gem安装compass:

linux
gem 'compass', :path => "/Users/myusername/some/path/to/compass"

ruby将自动执行捆绑命令

配置ruby目录 . ruby的加载路径可以这么设置

export RUBYLIB=/Users/myusername/some/path/to/compass/lib

运行测试

你必须安装Ruby到你的系统. 配置完git, 切换到root目录通过git checkout到compass分支

cd compass

捆绑安装Ruby gem.

gem install bundler

用sudo安装gems,

配置依赖:

bundle install --binstubs devbin

核心库和样式测试:

bundle exec rake test features

运行性能测试

./devbin/cucumber

如果样式测试失败, 捕获输出的测试项目在

test/fixtures/stylesheets/<project>/saved/

编写样式测试

Compass已经对每个样式表测试, 直接可以导入任何其他依赖关系和重构，不会影响到输出.

在某种程度上，在不同的浏览器测试是一项巨大工程。如果你有想法，请让我们知道如何做到这一点
在test/fixtures/stylesheets目录, 有许多的compass项目. 测试添加更新文件,修改错误保证他们都通过. 安全起见，它可能错过一些问题。如果您添加一个新的样式表到compass，请确保添加一个新样式表，增加新的样式规则。

重新选择或重新定位. 我们该怎么办?

根据任何数目的原因，包括但不限于星星多少，您的更改不会简单合并到compass。例如，我们会考虑master的稳定，而不是改变的地方，或者我们可以把所有同类更改合并在一起，形成一个单一的提交在时间，或者我们可能希望改变你已经提交，它被安置到顶部但没有改变。在这些情况下，有两种方法你有两种选择:

1.如果您有一些变化的一个分支，尚未接受，但其他分支上的变化被接受，那么您应该运行以下命令（确保fetch最新）:

git checkout branch_name; git rebase chriseppstein/master
(假设的变化应用到主分支)

2.
如果你所有在分支的改变被接受或你不想再保留:

git checkout master; git branch -D branch_name; git push origin :branch_name

创建Compass扩展

Compass扩展

Compass,其核心，是在Sass基础上建立的框架。它是提供创建，安装和可重复使用的样式表的工具，它提供从全面布局小部件框架设计，甚至整页的设计。Sass让HTML页面的语义明确的和设计细节省力。
本文档描述了compass扩展的工具集，这样您就可以建立你自己的compass的扩展。

基础布局

my_extension
|
|- stylesheets (sass加载路径)
|  |
|  |- my_extension (不是必须，但可以方便扩展)
|  |  |
|  |  |- _module_one.sass (可以通过 @import my_extension/module_one.sass导入)
|  |  |- _module_two.sass (可以通过@import my_extension/module_two.sass导入)
|  |  |- ...
|  |
|  |- _my_extension.sass (可以通过 @import my_extension.sass全部导入)
|
|- templates (templates/patterns)
|  |
|  |- project (项目)
|  |  |
|  |  |- manifest.rb (声明)
|  |  |- screen.sass (主样式表)
|  |  |- print.sass (输出样式表)
|  |  |- ie.sass (针对ie的样式表)
|  |
|  |- some_pattern
|     |
|     |- manifest.rb
|     |- some.sass (导入的第三方工具)
|     |- some_script.js (js)
|     |- some_image.png (图片)
|     |- some_content.html.haml (html 和 haml)
|     |- some_other_file.txt (任意文件)
|
|- lib (ruby配置)
   |
   |- my_extension.rb (注册修改框架配置)
   |- compass-my_extension.rb T自动加载. 可以通过 -r 命令阻止.)
   |
   |- my_extension
      |
      |- sass_extensions.rb (sass标准函数)

粗体部分的名称是扩展的命名约定的一部分。

生成扩展

如果你想扩展,可以通过compass的命令:

compass create my_extension --using compass/extension

这个会创建一些初始的文件和文件夹

如果你喜欢用scss语法可以通过下面命令:

compass create my_extension --using compass/extension -x scss

高级布局配置

库文件的位置

库引自 my_extension/lib/my_extension.rb 存的三个位置:

my_extension/compass_init.rb

my_extension/lib/my_extension.rb (注意:这个必须引入)

my_extension/my_extension.rb

这个地方将被首先加载。compass_init.rb文件优先，这样，作为compass扩展要针对不同的工作，更有针对性。

样式表和模板

如果您想存储您的样式表/或模板，在您的扩展内的一个非标准的位置，您必须提供一个库文件和注册了这些扩展明确，像这样:

base_directory  = File.join(File.dirname(__FILE__), '..')
stylesheets_dir = File.join(base_directory, 'my', 'stylesheets')
templates_dir   = File.join(base_directory, 'my', 'templates')
Compass::Frameworks.register('my_extension', :stylesheets_directory => stylesheets_dir, :templates_directory => templates_dir)

如果你是以下的标准命名约定，但没有在顶级样式表和模板目录，你可以这样做:

把compass保存在库文件路径。

base_directory  = File.join(File.dirname(__FILE__), '..', 'compass')
Compass::Frameworks.register('my_extension', :path => base_directory)

添加Compass配置

约定:

这不是必须，但你的框架最好尽可能坚持。

单一入口

拆分框架到模块，这样在不全部引入时，速度更快。

把样式表拆分成部分 (以_为开头的文件) 导入. 如果你不那么做
sass会生成css文件.

提供一个项目模板. I如果你不那么做, 至少提供一部分或者页面

创建模板(a.k.a. 规范)

Manifest Files 元文件

元文件声明模板包含的compass文件信息

示例

description "My awesome compass plugin."

stylesheet 'screen.sass', :media => 'screen, projection'
stylesheet 'partials/_base.sass'
stylesheet 'print.sass',  :media => 'print'
stylesheet 'ie.sass',     :media => 'screen, projection', :condition => "lt IE 8"

image 'grid.png'
javascript 'script.js'

html 'welcome.html.haml', :erb => true
file 'README'

help %Q{
	帮助信息
}

welcome_message %Q{
在用户安装的时候指导如果安装
}

可以去下面看看例子

blueprint

compass-css-lightbox

https://github.com/mirisuzanne/compass-css-lightbox/blob/master/templates/project/manifest.rb

Manifest 声明

简单模式: 如果你只需要一些基本文件，并没什么特别的事，简单地把这一行放在你的清单:

discover :all

如果文件丢失，discover :all 是缺省

这将导致compass找到所有你的模板文件，并使用文件扩展名来判断应该去的地方。或者，您也可以限定compass发现某一类型的文件。比如说，以下只会发现，JavaScript，图像，你也可以声明其他文件类型。

discover :javascripts
discover :images

下面将发现: :stylesheets, :images, :javascripts, :fonts, :html, :files, and :directories

普通模式: 7中声明方式:

stylesheet - Declares a sass file.
image - Declares an image.
javascript - Declares a javascript file.
font - Declares a font file.
html - Declares an html file.
file - Declares a random file.
directory - Declares a directory should be created.

所有声明的文件的路径作为他们的第一个参数。请注意，正常/可以而且应该使用。compass会兼顾所有平台的问题。文件的路径将在用户的项目，所以请记住这一点当创建文件夹。要安装文件的位置取决于用户的项目配置，模板可以向这些地点相对子目录的东西的地方。

常规配置:

:erb - 设置为true时，通过ERB模板语言。下面会有详细介绍。
:to - 应该相对安装文件的位置。

:like - 最常用的与文件声明，此选项允许您安装到另一个位置的类型（包括:CSS）。例如。:like => :css

:media - 这是用来作为一个提示用户关于媒体属性的样式表链接的标记。

:condition - 这是用来提示用户，应使用给定的条件下，导入的样式表。

目录配置:

在哪里应该创建该目录。如果省略，则相对于项目目录的目录。可以是下列值之一:以下

sass_dir
javascripts_dir
fonts_dir
images_dir
HTML files:

HAML可以提供HTML或纯HTML。如果您提供HAML，HAML的安装时，它将被转换为HTML，除非项目允许HAML文件。提供HTML文件通常是以演示如何使用一个更复杂的设计和获得用户开始工作产品。

高级Manifests模板

ERB（ruby脚本）Processing - 这可用于在一个扩展自定义文件的内容模板。模板将模板内容的上下文中处理成实例，从而使您可以访问完整的项目配置信息，以及作为命令行选项。因为它是不太可能有大量模板将需要此功能，我把它作为一个练习，开发者可以邮件咨询。

no_configuration_file! - 调用此方法将告诉安装程序清单内跳过创建一个配置文件。

skip_compilation! - 会告诉安装程序清单内调用此方法跳过Sass的CSS文件汇编。

Ruby Gems分布扩展

RubyGems是一个灵活，易用的系统，为分布式Ruby软件。RubyGems如果你有任何疑问，我建议你开始寻找帮助。

分发您的扩展使用RubyGems大优势是，它允许您的扩展将其他项目的依赖项和每个安装的版本，这使得支持您的扩展变得更加容易。

如果作为一个RubyGem分配，这是一个好主意，有一个compass.rb在你的lib目录中注册的compass框架。这将使compass自动加载RubyGems内框架。

研发技巧

如果你研发一个简单的扩展, 你会发现在已有项目文件夹内开发会非常便捷.

如没有指定一个扩展你的时候进口，会造成问题的文件的语法变化。

发布

版本

方便用户使用。 通过打捆工具集成与Ruby为基础的项目。

创建Gem

在您开始之前，请确保你的ruby版本1.3。6或更高版本 ruby -v 可以检测版本

在您的扩展顶部定义gemspec文件。这里的一个例子。gemspec应该与gem有相同的名称。

通过添加 lib/my_extension.rb 注册到框架:

require 'compass'
extension_path = File.expand_path(File.join(File.dirname(__FILE__), ".."))
Compass::Frameworks.register('my_extension', :path => extension_path)

这就是compass知道在哪里可以找到您的扩展文件，当用户需要它。更多选项，去备份和阅读样式表和模板的位置。

创建 gem: gem 创建 my_extension.gemspec. 创建gem并添加版本到名字 . 例如. my_extension-0.0.1.gem

测试: gem install my_extension-0.0.1.gem

发布gem

ruby社区是一个免费发布的平台:

gem push my_extension-0.0.1.gem

你的ruby gem发布到rubygems.org. 请关注他们

安装扩展

如何安装扩展是根据你所做的决定如何，你的包装发布你的gem。将在将来的版本中的标准方法，但在那之前，建议您为您的用户提供简洁的安装说明。

通过RubyGems安装发布

创建一个新的项目:

sudo gem install my_extension

compass create my_project -r my_extension --using my_extension

-r 配置忽略未来版本. 但是现在, 从本地加载rubygems镜像.

通过安装rubygems进入已经存在项目:

gem install my_extension

编辑添加配置文件

require 'my_extension'
compass install my_extension

或者添加以下规范到文件里:

compass install my_extension/pattern
Installing Ad-hoc Extensions

Ad-hoc扩展的任何一组文件和上文所述的基本公约的以下文件夹。他们可以通过一个ZIP文件安装或从源代码管理中，通过检查代码。Ad-hoc的扩展将被自动发现在一个项目的扩展目录和进口注册，而无需一个require语句在compass的配置文件。

目前，Ad-hoc扩展一些广告暂时只能安装到现有的compass项目的扩展目录。这个问题将在未来解决。在那之前，您可能需要将指导您的用户可以创建一个项目开始:

compass create my_project --bare

这将创建一个项目栌, 一个sass目录 (没有文件)和一个配置文件.

为扩展的标准位置对于独立的项目和
project_root/vendor/plugins/compass_extensions project_root/extensions Rails项目。此外，用户可以定制他们在他们的compass项s的extensions_dir通过设置扩展目录的配置文件。

安装到现有的项目，将扩展到项目的扩展目录。这可以通过一个git克隆或提取的存档。它创建的目录的名称应扩展的名称。该项目将获得扩展。

验证扩展是正确安装

用户可以通过输入验证他们访问您的扩展:
compass help

他们应该可以看到列表中的可用框架的框架。或者，如果您已经在元文件中提供帮助信息:

compass help my_extension

或者

compass help my_extension/pattern_name

注意:用户可能需要提供-R选项，方便回退。这不是需要扩展安装到扩展目录，或者如果所需要的项目已经在当前目录中的项目配置。

Compass的扩展

雪碧图引擎

雪碧图引擎是一个合成图片的接口

要求

获取雪碧图引擎的两种方式 construct_sprite, 和 save(filename)

引入后就可以访问合成的图片了

配置

在配置文件里打开雪碧图

sprite_engine = :<engine name>

以下例子将加载

Compass::SassExtension::Sprites::ChunkyPngEngine.new(width, height, images)

sprite_engine = :chunky_png

类定义

module Compass
  module SassExtensions
    module Sprites
      class ChunkyPngEngine < Compass::SassExtensions::Sprites::Engine

        def construct_sprite
          #do something
        end    

        def save(filename)
          #save file
        end

      end
    end
  end
end

增加配置属性到Compass

Compass::Configuration.add_configuration_property(:foobar, "this is a foobar") do
  if environment == :production
    "foo"
  else
    "bar"
  end
end

这将做几件事:

1,让用户可以设置foobar它们的配置文件中配置属性。

2,foobar的Ruby代码可以读取和写入的任何配置对象的属性。 

3,# this is a foobar中。注释不是必需的，你可以简单的忽略，如果你喜欢

4,提供的代码块允许您指定一个合理的根据其他设置的默认值的配置或使用任意代码以确定什么价值应该是开的。例如，它可以读取一个配置文件，也可以基于用户的操作系统的变化。

生成样式表

可以参考可用的配置选项。

用于生成的编译样式表

配置 A: 默认

compass compile -e production --force

注:这是compass的默认值，您所指定的选择中显式地配置不会改变。

配置 B: 覆盖您的配置文件设置

compass compile --output-style compressed --force

配置 C: 创建一个单独的配置文件用于生产

cp config.rb prod_config.rb


..edit prod_config.rb to suit  your needs..

compass compile -c prod_config.rb --force

精灵图

精灵图

ps:精灵图和雪碧图 都是一个

Compass让创建精灵图更简单. 你可以把精灵图片放到一个文件夹下, 导入你的样式表, 你可以通过多种方法使用雪碧图

*主:必须是https://github.com/wvanbergen/chunky_png支持的.

安装

下面我们打包4个icons:

images/my-icons/new.png
images/my-icons/edit.png
images/my-icons/save.png
images/my-icons/delete.png

相互间隔32px.

基本用法

**注意: my-icons 只适用于本例, “my-icons” 代表包含您的精灵文件夹名称。

最简单的方法就是单独使用类:

@import "compass/utilities/sprites";
@import "my-icons/*.png";
@include all-my-icons-sprites;

你将获得CSS输出:

.my-icons-sprite,
.my-icons-delete,
.my-icons-edit,
.my-icons-new,
.my-icons-save   { background: url('/images/my-icons-s34fe0604ab.png') no-repeat; }

.my-icons-delete { background-position: 0 0; }
.my-icons-edit   { background-position: 0 -32px; }
.my-icons-new    { background-position: 0 -64px; }
.my-icons-save   { background-position: 0 -96px; }

你可以使用 my-icons-XXX类来标记需要。

我们分析下原理。import语句告诉compass生成的样式表定制你的精灵。这个样式表是有魔力的，它是不会写到硬盘上，并且可以自定义设置你之前导入配置变量。看到自定义选项页。这个样式表的目标是提供一个简单的命名惯例，为你的精灵，让他们很容易记住和使用。你不该关心什么是雪碧地图生成的名字，也没有一杯雪碧是位于哪里的。

嵌套文件夹

这个例子中我们使用橙子图片，“橘子”代表了文件夹名称包含您的精灵。 精灵存储在嵌套文件夹将使用去年在雪碧的路径名称的文件夹名称。

例如:

@import “themes/orange/*.png”;
@include all-orange-sprites;

选择器控制

我使用的my-icons图标，“my-icons”代表了文件夹名称包含您的精灵。 如果你想控制选择器生成，它是容易做到的。在这个例子中，这是通过使用mixin的魔我的-图标-雪碧。请注意，mixin的名字是依赖于在你已经把你的文件夹的名称的图标

@import "my-icons/*.png";

.actions {
  .new    { @include my-icons-sprite(new);    }
  .edit   { @include my-icons-sprite(edit);   }
  .save   { @include my-icons-sprite(save);   }
  .delete { @include my-icons-sprite(delete); }
}
你的样式表编译为:

.my-icons-sprite,
.actions .new,
.actions .edit,
.actions .save,
.actions .delete { background: url('/images/my-icons-s34fe0604ab.png') no-repeat; }

.actions .new    { background-position: 0 -64px; }
.actions .edit   { background-position: 0 -32px; }
.actions .save   { background-position: 0 -96px; }
.actions .delete { background-position: 0 0;     }

Sass 函数

雪碧得到的图像尺寸

可以通过

Example:

@import "my-icons/*.png";
$box-padding: 5px;
$height: my-icons-sprite-height(some_icon);
$width: my-icons-sprite-width(some_icon);

.somediv {
  height:$height + $box-padding;
  width:$width + $box-padding;
}

精灵导入

正如上文所指出的，Compass会用精灵函数创造的雪碧你的样式表。有些人喜欢精灵，有些人害怕它，和其他人都很好奇是如何工作的。如果你想避免的精灵函数，您可以使用Compass为你生成导入。在命令行中:

compass sprite “images/my-icons/*.png”

这将创建的文件使用您的项目，或者您可以指定输出文件名使用-f选项和语法将从扩展。如果你这么做，你要记得无论何时重命名导入，再生添加，或删除一个小精灵。

大多数情况下建议使用精灵导入。但有些时候，您可能希望避免它。例如，如果您的精灵地图已超过20至30，你会发现手工导入将增加时间。请参阅性能上的考虑，更多的细节。

要考虑的一些性能

阅读PNG文件和组装新的图像，并将它们保存到磁盘可能影响样式表编译时间。特别是第一次编译。请记住这一点。

大量的精灵

精灵样式表可以变得非常大时，有大量的精灵。50精灵会导致有超过150变量，然后传递到精灵map函数。雪碧你可能会发现，自定义的函数调用，只有通过这些方式，你是最会提供一个小的性能提升。看一个具体的例子。

Oily PNG

Compass生成PNG文件，使用纯Ruby库，即chunky_png。这个库可以通过安装一个简单的C扩展称为oily_png更快。添加到您的Gemfile以声明依赖性之后如果你有一个在您的项目:

gem ‘oily_png’
或者 install the Rubygem:

gem install oily_png
Compass自动地检测它的存在

定制

定制配置

全局配置

这些选项允许您自定义您的样式表中引用的所有sprite的行为。在许多情况下，有一个配置选项，允许您更改默认为雪碧地图，甚至个别Sprite图像。

NOTE: 这些精灵导入之前，必须先设置配置选项。

$sprite-selectors - 取决于创建选择器的精灵。

$disable-magic-sprite-selectors - 关掉精灵选择器设置为true。默认值为false。

$default-sprite-separator - 默认加破折号。你可以任意设置它一个下划线（“_”）如果你是这些人之一。

精灵的选项

构建雪碧地图时，整个精灵地图及其相关联的样式表可以被配置为在以下几个方面。通过设置每个选项指定的配置变量之前进口的雪碧。变量的命名是由sprite包含文件夹的名称。下面的例子中的精灵被包含在文件夹图标

$<map>-spacing -- 透明的空间量，以像素为单位，每个雪碧。默认为0像素px. E.g. $icon-spacing: 20px.

$<map>-repeat -- 每个sprite是否应重复沿着x轴. 默认不重复. E.g. $icon-repeat: repeat-x.
n t
$<map>-position -- 在雪碧的位置沿X轴的地图。可以指定sprite地图的宽度的像素或百分比。100%会靠近雪碧的右边上的地图。默认为0像素。 E.g. $icon-position: 100%.

$<map>-sprite-dimensions --精灵的尺寸是否应包括在每个sprite的CSS输出。可以是真或伪。默认值为false。


这些精灵的基类。默认为。-雪碧。.<map>-sprite:“。”行动纲领“图标” $-清理-是否要清除旧的雪碧，当创建一个新的文件。默认值是true

$<map>-clean-up -- 是否要清除旧的雪碧，当创建一个新的文件。默认值是true

$<map>-class-separator -- 如果您设置了这个以一个下划线（“_”），那么所有生成的这个雪碧的选择器将使用下划线而不是破折号。更改此值为全部精灵而创建，设置$默认下划线-雪碧-分离器。 每个精灵的选项

精灵的选项

构建雪碧地图时，每个精灵都可以配置为在以下几个方面:

$<map>-<sprite>-spacing -- 透明的空间量，以像素为单位，围绕雪碧。默认值为雪碧地图默认为0像素的间距。. E.g. $icon-new-spacing: 20px.

$<map>-<sprite>-repeat -- 雪碧是否应重复沿着x轴。默认值为雪碧默认为无地图的重复重复. E.g. $icon-new-repeat: repeat-x.

$<map>-<sprite>-position -- 在雪碧的位置沿X轴的地图。可以指定sprite地图的宽度的像素或百分比。100%会导致雪碧靠右边上的地图。默认为雪碧地图的位置值默认为0像素。. E.g. $icon-new-position: 100%.

Magic Selectors

Magic Selectors

If you want to add selectors for your sprites, it’s easy todo by adding _active _target or _hover to the file name, In the example below we have a sprite directory that looks like: note you can use - in file names also ex. glossy-active.png my-buttons/glossy.png my-buttons/glossy_hover.png my-buttons/glossy_active.png my-buttons/glossy_target.png

sass文件添加:

@import "my-buttons/*.png";

a {
  @include my-buttons-sprite(glossy)
}
编译为:

.my-buttons-sprite, a {
  background: url('/my-buttons-sedfef809e2.png') no-repeat;
}

a {
  background-position: 0 0;
}
a:hover, a.glossy_hover, a.glossy-hover {
  background-position: 0 -40px;
}
a:target, a.glossy_target, a.glossy-target {
  background-position: 0 -60px;
}
a:active, a.glossy_active, a.glossy-active {
  background-position: 0 -20;
}

或者，您可以使用 @include all-my-buttons-sprites; 引入后得到以下输出

.my-buttons-sprite, .my-buttons-glossy {
  background: url('/my-buttons-sedfef809e2.png') no-repeat;
}

.my-buttons-glossy {
  background-position: 0 0;
}
.my-buttons-glossy:hover, .my-buttons-glossy.glossy_hover, .my-buttons-glossy.glossy-hover {
  background-position: 0 -40px;
}
.my-buttons-glossy:target, .my-buttons-glossy.glossy_target, .my-buttons-glossy.glossy-target {
  background-position: 0 -60px;
}
.my-buttons-glossy:active, .my-buttons-glossy.glossy_active, .my-buttons-glossy.glossy-active {
  background-position: 0 -20px;
}

禁用

在调用选择器$disable-magic-sprite-selectors 取消这个特效

a {
$disable-magic-sprite-selectors:true;
@include my-buttons-sprite(glossy)
}

精灵布局

顺序

默认sprite按照他们收到从文件系统顺序
你可以设置:

width
height
size
name
none
示例

$my-sprite-sort-by : ‘width’;
Default search direction is acending if you wish to sort decending prepend a !

$my-sprite-sort-by : ‘!width’;
Sprite Layouts

示例:

$icon-layout:horizontal;
@import “icon/*.png”;

$dropcap-layout:diagonal
@import “dropcap/*.png”;
Vertical

@import “mysprite/*.png”;
实例输出:

垂直示例

水平

$mysprite-layout:horizontal;
@import “mysprite/*.png”;
实例输出:

水平实例

Notes:

响应垂直相同的配置选项
Diagonal

$mysprite-layout:diagonal;
@import “mysprite/*.png”;
实例输出:

倾斜实例

Notes:

配置选项不影响布局
这是令人难以置信的资源密集的浏览器上

$mysprite-layout:smart;
@import “mysprite/*.png”;

示例输出:

简单例子

Notes:

配置选项不影响布局
最有效地利用浏览器存储器
从公开的图标图标库的例子和在公共领域发布

测试

单元测试

require 'compass/test_case'
class StylesheetsTest < Compass::TestCase
  def test_stylesheets
    my_sass_files.each do |sass_file|
      assert_compiles(sass_file) do |result|
        assert_not_blank result
      end
    end
  end
  protected
  def my_sass_files
    Dir.glob(File.expand_path(File.join(File.dirname(__FILE__), "../..", "app/stylesheets/**/[^_]*.sass")))
  end
end

升级(不再维护，这个不用看啦)

配置变量

Sass中有两种定义变量的方法. 第一种，最常见的:

$my-constant : #fedcba

第二种是提供一个默认值。比如说:

$my-constant : #fedcba !default

许多模块允许你设置默认值，导入模块之前，您必须设置变量。比如说:

$blueprint-grid-columns = 12
@import "blueprint/grid"

因此，把多个部分引入一个。这通常被称为“base”命名样式表通常是 _base.scss or _base.sass.

Examples不考虑翻译

Documentation不考虑翻译

Support不考虑翻译

Bugs不考虑翻译