Toolkit工具包

The Susy 2.0 toolkit is built around our shorthand syntax. Use the shorthand to control every detail, and adjust your defaults on-the-fly, so you are never tied down to just one grid, or just one output style.

Susy 2.0 工具包建立在速记语法的基础上，使用速记可以控制每一个细节，在传输过程中可以做到适时调整，在你书写一个网格，或者输出样式的时候都没有问题。

Span [mixin]混入

Set any element to span a portion of your layout. For a floated or isolated layout, this will add necessary floats, widths, and margins.

在布局的任意部分使用span。浮动或者单独隔离的布局，会生成必要的floats, widths, and margins属性。

mixin

Format:	span($span) { @content }
$span:	<span>
@content:	Sass content block

There are many ways to use the span mixin...使用span混入的发放有几种

Arbitrary Widths 定制宽度

For the simplest use, pass any width directly to the mixin: 最简单的使用，越过宽度直接到混入

// arbitrary width
.item { @include span(25%); }

// float output (without gutters)
.item {
  float: left;
  width: 25%;
}

Grid Widths 网格宽度

If you are using a grid, you can also span columns on the grid: 如果你正在使用一个网格，你也能在网格中设置列数

// grid span
.item { @include span(3); }

// output (7-column grid with 1/2 gutters after)
.item {
  float: left;
  width: 40%;
  margin-right: 5%;
}

Row Edges 行边距

When you use a grid with gutters before or after, you sometimes need to mark the first or last elements in a row, so Susy can remove the extra gutters:

当你在网格中给gutters使用before或者after时，你通常需要在行中标记出first或者last，这样Susy就可以移除额外的gutters.

// grid span
@include span(last 3);

// output (same 7-column grid)
.item {
  float: right;
  width: 40%;
  margin-right: 0;
}

For legacy reasons, alpha and omega can be used in place of first and last. 对于继承，alpha可以代替first,omega可以代替last

Context上下文

Context is required any time you are using fluid math, and nesting grid elements inside other elements:

在使用流体布局和在其他元素内部嵌套网格的时，Context(上下文)始终都是需要的.

// 10-column grid
.outer {
  @include span(5);
  .inner { @include span(2 of 5); }
}

The of flag is used to signal context. The context is always equal to the grid-span of the parent. In some cases, you can imply changes in context by nesting elements inside the span tag itself:

of标识通常作为Context信号，Context一直等同于父级的grid-span.在一些案例中，你可以在一span内部再次嵌套span并将这些改变作用于上下文。

// 10-column grid
.outer {
  // out here, the context is 10
  @include span(5) {
    // in here, the context is 5
    .inner { @include span(2); }
  }
}

Nesting 嵌套

Grids with inside, inside-static, or split gutters don’t need to worry about the edge cases, but they do have to worry about nesting.

If an element will have grid-aligned children, you should mark it as a nest:

带有inside, inside-static, or split的网格 的分隔，不需要关心边界的情况，但是如果是嵌套类型的话还是需要关心的。如果一个元素包含了一个网格对齐的子元素，你应该给她标识成nest:

// inside, inside-static, or split gutters
.outer {
  @include span(5 nest);
  .inner { @include span(2 of 5); }
}

Location 定位

Asymmetrical grids and isolated output also need to know the desired location of the span. In both cases, use the at flag to set a location.

For isolation, you can use either an arbitrary width or a column index (starting with 1). For asymmetrical grid spans, the location setting must be a column index:

非对称网格和分隔输出的网格需要知道想得到span的定位，在上述案例中，使用at标识去设置一个定位

对于分隔而言，也既可以使用自定义的宽度，也可以使用列索引（从1开始），对于不对称网格，定位设置应该是一个列索引。

.width { @include span(isolate 500px at 25%); }
.index { @include span(isolate 3 at 2); }

narrow, wide, and wider狭窄，宽，更宽

By default, a grid span only spans the gutters between columns. So a span of 2 includes 1 internal gutter (narrow). In some cases you want to span additional gutters on either side. So that same span of 2 could include the internal gutter, and one (wide) or both (wider) external gutters.

默认情况下，一个网格span仅仅在列之间生成间隔。就如一个2包含1（狭窄）的span。在一些案例中你想要在其他边分隔额外的间隔。那样的话2个span可以包含额外的间隔，一个宽或者更宽的可以生成更大的间隔

// grid span
.narrow { @include span(2); }
.wide { @include span(2 wide); }
.wider { @include span(2 wider); }

// width output (7 columns, .25 gutters)
// (each column is 10%, and each gutter adds 2.5%)
.narrow { width: 22.5%; }
.wide { width: 25%; }
.wider { width: 27.5%; }

If you are using inside gutters, the spans are wide by default but can be overridden manually.如果你正在使用内部沟槽，spans可以被默认或者手动覆盖

Other Settings 其他设置

Use the full keyword to span the entire context available, use break to start a new Rows & Edges by clearing previous floats, and nobreak to clear none. Use no-gutters to remove gutter output from an individual span, and use border-box or content-box to output changes in box-sizing on the fly.

You can set an arbitrary gutter override, by passing a map (e.g. (gutter-override: 1.5em)) as part of the shorthand syntax.

You can also change the output style, grid context, and other global settings on the fly:

在所有可用的上下文环境中，所有的关键词都是可用的。使用break可以开始一个新的行或者边，靠清除之前的浮动，nobreak去清除none。使用no-gutters去移除分隔输出从单独的span，使用border-box或者content-box去输出改变在box-sizing在执行中时

.item { @include span(isolate 4 at 2 of 8 (4em 1em) inside rtl break); }

// output
.item {
  clear: both;
  float: right;
  width: 50%;
  padding-left: .5em;
  padding-right: .5em;
  margin-left: 25%;
  margin-right: -100%;
}

Span [function]

The span function is identical to the span mixin, but returns only the span width value, so you can use it with custom output.

function

Format:	span($span)
$span:	<span>

.item {
  width: span(2);
  margin-left: span(3 wide);
  margin-right: span(1) + 25%;
}

Gutters

function/mixin

Format:	gutters($span)
Alternate:	gutter($span)
$span:	<span>

Use gutter or gutters as a function to return the width of a gutter given your settings and current context.

// default context
margin-left: gutter();

// nested in a 10-column context
margin-left: gutter(10);

Use the mixin version to apply gutters to any element. Gutters are output as margin or padding depending on the gutter-position setting.

// default gutters
.item { @include gutters; }

You can also set explicit gutter widths:

// explicit gutters
.item { @include gutters(3em); }

Or use the shorthand syntax to adjust settings on the fly:

// inside gutters
.item { @include gutters(3em inside); }

// gutters after, in an explicit (10 1/3) layout context
.item { @include gutters(10 1/3 after); }

Container

function/mixin

Format:	container($layout)
$layout:	<layout>

Use the container function to return a container-width based on an optional layout argument, or your global settings.

// global settings
width: container();

// 12-column grid
$large-breakpoint: container(12);

Use the mixin to apply container settings to an element directly.

body {
  @include container(12 center static);
}

Note that static math requires a valid column-width setting

Nested Context

function/mixin

Function:	nested($span)
Mixin:	nested($span) { @content }
$span:	<span>
@content:	Sass content block

Sass is not aware of the DOM, or the specific markup of your site, so Susy mixins don’t know about any ancestor/child relationships. If your container creates a grid context that is different from the default, you will need to pass that new context explicitly to nested elements.

You can pass that context along with the shorthand syntax.

body { @include container(8); }
.span { @include span(3 of 8); }

But that gets repetitive if you have large blocks of code using a given context. The nested mixin provides a shortcut to change the default context for a section of code.

@include nested(8) {
  .span { @include span(3); }
}

Context is a bit more complex when you are using asymmetrical grids, because we need to know not just how many columns, but which columns are available.

.outer {
  @include span(3 of (1 2 3 2 1) at 2);

  // context is now (2 3 2)...
  .inner { @include span(2 of (2 3 2) at 1); }
}

The nested function can help you manage context more easily, without having to calculate it yourself.

$grid: (1 2 3 2 1);

.outer {
  @include span(3 of $grid at 2);

  $context: nested(3 of $grid at 2);
  .inner { @include span(2 of $context at 1); }
}

Global Box Sizing

Set the box-sizing on a global selector, and set the global-box-sizing to match.

mixin

Format:	global-box-sizing($box [, $inherit])
Shortcut:	border-box-sizing([$inherit])
$box:	content-box | border-box
$inherit:	[optional] true | false

Setting the optional argument, $inherit, to true will still globally set the box-sizing, but in a way such that a component can easily override the global box-sizing by setting its own box-sizing property. By setting box-sizing once on the component, all nested elements within the component will also be modified. The default behavior, where $inherit is false, would only update the box-sizing of the component itself. Nested elements are not affected when $inherit is false.

You can pass a box-sizing argument to the span mixin as part of the shorthand syntax, and Susy will set the element’s box-sizing to match.

// input
.item { @include span(25em border-box); }

// sample output (depending on settings)
.item {
  float: left;
  width: 25em;
  box-sizing: border-box;
}

We highly recommend using a global border-box setting, especially if you are using inside gutters of any kind.

// the basics with default behavior:
* { box-sizing: border-box; }

// the basics with $inherit set to true:
html { box-sizing: border-box; }
* { box-sizing: inherit; }

Susy needs to know what box model you are using, so the best approach is to set global box sizing using one of Susy’s shortcuts.

// the flexible version:
@include global-box-sizing(border-box);

// the shortcut:
@include border-box-sizing;

If you want to change the global box-sizing by hand, or it has already been changed by another library, update the global-box-sizing setting to let Susy know.

If you need to supprot IE6/7, there is a simple polyfill to make it work.

Rows & Edges

Floated layouts sometimes require help maintaining rows and edges.

Break

mixin

Format:	break()
Reset:	nobreak()
Keywords:	break | nobreak

To create a new row, you need to clear all previous floats. This can usually be done using keywords with the span mixin. When you need to apply a row-break on it’s own, we have a break mixin.

.new-line { @include break; }

If you ever need to override that, you can use nobreak to set clear: none;.

.no-new-line { @include nobreak; }

Both break and nobreak can also be used as keywords with the span mixin.

First

mixin

Format:	first($context)
Alternate:	alpha($context)
$context:	<layout>

Note

Only useful when gutter-position is set to before.

When gutter-position is set to before we need to remove the gutter from the first element in every row. This can often be solved using a keyword in the span mixin. Sometimes you need to set an item as first outside the span mixin.

.first { @include first; }

We also support an alpha mixin with the same syntax and output.

Both first and alpha can also be used as keywords with the span mixin.

Last

mixin

Format:	last($context)
Alternate:	omega($context)
$context:	<layout>

Note

Only required when gutter-position is set to after, but can be useful in any context to help with sub-pixel rounding issues.

When gutter-position is set to after we need to remove the gutter from the last element in every row, and optionally float in the opposite direction. This can often be solved using a keyword in the span mixin. Sometimes you need to set an item as last outside the span mixin.

.last { @include last; }

We also support an omega mixin with the same syntax and output.

Both last and omega can also be used as keywords with the span mixin.

Full

mixin

Format:	full($context)
$context:	<layout>

This is a shortcut for span(full), used to create elements that span their entire context.

.last { @include full; }

full can also be used as a keyword with the span mixin.

Margins

Shortcut mixins for applying left/right margins.

Pre

mixin

Format:	pre($span)
Alternate:	push($span)
$span:	<span>

Add margins before an element, depending on the flow direction.

.example1 { @include pre(25%); }
.example2 { @include push(2 of 7); }

Post

mixin

Format:	post($span)
$span:	<span>

Add margins after an element, depending on the flow direction.

.example1 { @include post(25%); }
.example2 { @include post(2 of 7); }

Pull

mixin

Format:	pull($span)
$span:	<span>

Add negative margins before an element, pulling it against the direction of flow.

.example1 { @include pull(25%); }
.example2 { @include pull(2 of 7); }

Squish

mixin

Format:	squish($pre [, $post])
$pre:	<span>
$post:	[optional] <span>

Shortcut for adding both pre and post margins to the same element.

// equal pre and post
.example1 { @include squish(25%); }

// distinct pre and post
.example2 { @include squish(1, 3); }

When they share identical context, you can pass pre and post spans in the same argument. This is often the case, and saves you from repeating yourself.

// shared context
.shared {
  @include squish(1 3 of 12 no-gutters);
}

// distinct context
.distinct {
  @include squish(1 at 2, 3 at 6);
}

Padding

Shortcut mixins for applying left/right padding.

Note

The interaction between padding and width changes depending on your given box-model. In the browser-default content-box model, width and padding are added together, so that an item with span(3) and prefix(2) will occupy a total of 5 columns. In the recommended border-box model, padding is subtracted from the width, so that an item with span(3) will always occupy 3 columns, no matter what padding is applied.

Prefix

mixin

Format:	prefix($span)
$span:	<span>

Add padding before an element, depending on the flow direction.

.example1 { @include prefix(25%); }
.example2 { @include prefix(2 of 7); }

Suffix

mixin

Format:	suffix($span)
$span:	<span>

Add padding after an element, depending on the flow direction.

.example1 { @include suffix(25%); }
.example2 { @include suffix(2 of 7); }

Pad

mixin

Format:	pad($prefix [, $suffix])
$prefix:	<span>
$suffix:	<span>

Shortcut for adding both prefix and suffix padding to the same element.

// equal pre and post
.example1 { @include pad(25%); }

// distinct pre and post
.example2 { @include pad(1, 3); }

When they share identical context, you can pass pre and post spans in the same argument. This is often the case, and saves you from repeating yourself.

// shared context
.shared {
  @include pad(1 3 of 12 no-gutters);
}

// distinct context
.distinct {
  @include pad(1 at 2, 3 at 6);
}

Bleed

mixin

Format:	bleed($bleed)
$bleed:	TRBL <span>

Apply negative margins and equal positive padding, so that element borders and backgrounds “bleed” outside of their containers, without the content be affected.

This uses the standard span shorthand, but takes anywhere from one to four widths, using the common TRBL pattern from CSS.

// input
.example1 { @include bleed(1em); }
.example2 { @include bleed(1em 2 20px 5% of 8 .25); }

// output
.example1 {
  margin: -1em;
  padding: 1em;
}

.example2 {
  margin-top: -1em;
  padding-top: 1em;
  margin-right: -22.5%;
  padding-right: 22.5%;
  margin-bottom: -20px;
  padding-bottom: 20px;
  margin-left: -5%;
  padding-left: 5%;
}

When possible, the bleed mixins will attempt to keep gutters intact. Use the no-gutters keyword to override that behavior.

Bleed-x

mixin

Format:	bleed-x($bleed)
$bleed:	LR <span>

A shortcut for applying only left and right (horizontal) bleed.

// input
.example { @include bleed-x(1em 2em); }

// output
.example {
  margin-left: -1em;
  padding-left: 1em;
  margin-right: -2em;
  padding-right: 2em;
}

Bleed-y

mixin

Format:	bleed-y($bleed)
$bleed:	TB <span>

A shortcut for applying only top and bottom (vertical) bleed.

// input
.example { @include bleed-y(1em 2em); }

// output
.example {
  margin-top: -1em;
  padding-top: 1em;
  margin-bottom: -2em;
  padding-bottom: 2em;
}

Isolate

mixin

Format:	isolate($isolate)
$isolate:	<span>

Isolation is a layout technique based on floats, but adjusted to address sub-pixel rounding issues. Susy supports it as a global output setting, or as a Shorthand keyword for the span mixin, or as a stand-alone mixin.

The $isolate argument takes a standard span shorthand, but any length or grid-index given is interpreted as an isolation location (unless location is otherwise specified with the at flag). The function returns a length value.

// input
.function {
  margin-left: isolate(2 of 7 .5 after);
}

// output
.function {
  margin-left: 15%;
}

And the mixin returns all the properties required for isolation.

// input
.mixin { @include isolate(25%); }

// output
.mixin {
  float: left;
  margin-left: 25%;
  margin-right: -100%;
}

Gallery

mixin

Format:	gallery($span, $selector)
$span:	<span>
$selector:	(nth-) child* | of-type

Gallery is a shortcut for creating gallery-style layouts, where a large number of elements are layed out on a consistent grid. We take the standard span shorthand and apply it to all the elements, using nth-child or nth-of-type selectors and the isolation technique to arrange them on the grid.

// each img will span 3 of 12 columns,
// with 4 images in each row:
.gallery img {
  @include gallery(3 of 12);
}

Show Grid

mixin

Format:	show-grid($grid)
$grid:	<layout>

The easiest way to show you grids is by adding a keyword to your container mixin. If you need to apply the grid separately, the show-grid mixin takes exactly the same layout shorthand arguments, and can output the debugging grid image as either a background, or a triggered overlay.

body {
  @include container;
  @include show-grid(overlay);
}

Warning

Grid images are not exact. Browsers have extra trouble with sub-pixel rounding on background images. These are meant for rough debugging, not for pixel-perfect measurements. Expect the to side of your grid image (right if your flow is ltr) to be off by several pixels.

Breakpoint

Susy has built-in media-query handling, and also supports integration with the Breakpoint plugin. To install Breakpoint, follow the instuctions on their site.

Susy Breakpoint

mixin

Format:	susy-breakpoint($query, $layout, $no-query)
$query:	media query shorthand (see susy-media)
$layout:	<layout>
$no-query:	<boolean> | <string> (see susy-media)

susy-breakpoint() acts as a shortcut for changing layout settings at different media-query breakpoints, using either susy-media or the third-party Breakpoint plugin.

If you are using the third-party plugin, see Breakpoint: Basic Media Queries and Breakpoint: No Query Fallbacks for details.

This mixin acts as a wrapper, adding media-queries and changing the layout settings for any susy functions or mixins that are nested inside.

@include susy-breakpoint(30em, 8) {
  // nested code uses an 8-column grid,
  // starting at a 30em min-width breakpoint...
  .example { @include span(3); }
}

Susy Media

mixin

Format:	susy-media($query, $no-query)
$query:	<min-width> [<max-width>] | <string> | <pair> | <map>
$no-query:	<boolean> | <string>

The susy-media mixin provides basic media-query handling, and handles the built-in functionality for susy-breakpoint.

$query

A single length will be used as a min-width query, two lengths will become min- and max- width queries, a property-value pair, or map of pairs will become (property: value) queries, and a lonely string will be used directly.

// min
// ---
@include susy-media(30em) { /*...*/ }

@media (min-width: 30em) { /*...*/ }

// min/max pair
// ------------
@include susy-media(30em 60em) { /*...*/ }

@media (min-width: 30em) and (max-width: 60em) { /*...*/ }

// property/value pair
// -------------------
@include susy-media(min-height 30em) { /*...*/ }

@media (min-height: 30em) { /*...*/ }

// map
// ---
@include susy-media((
  min-height: 30em,
  orientation: landscape,
)) { /*...*/ }

@media (min-height: 30em) and (orientation: landscape) { /*...*/ }

$no-query

true will render the contents to css without any media-query. This can be useful for creating separate no-query fallback files.

For inline fallbacks using a target class, pass in a string (e.g. .no-mqs) to use as your fallback selector. The contents will be output both inside a media-query and again inside the given selector.

This can be set globally with the $susy-media-fallback variable.

susy-media also supports named media-queries, which can be set using the $susy-media variable:

$susy-media: (
  min: 20em,
  max: 80em 60em,
  string: ‘screen and (orientation: landscape)‘,
  pair: min-height 40em,
  map: (
    media: screen,
    max-width: 30em
  ),
);

@include susy-media(min);