知らないと損するSassの組み込み関数徹底解剖

Jul 14, 2015 sass

Sassを使うにあたって、覚えておくと必ず幸せになれる組み込み関数というものがある。
自分で定義できる @function とは違い、Sassに最初から備わっているものだ。
Sass自体の機能だから、もちろんCompassなどのフレームワークを使用する際も使うことができる。

普段Sassを使っているひとでも、Sassの組み込み関数については詳しく知らない人も多いのではないだろうか。
これを自由に使いこなすことが出来ればコーディングが楽になることは間違いない。
改めてドキュメントを見直すと自分の知らないものもあったため、今回全てをまとめてみた。

すぐに試してみたい人はこちらのデモを試してみるといい。

関数の呼び出し

シンプルにそのまま記述するだけ。

.rgb {
    color: lighten(#fff, 30%);
}

出力結果を文字列と連結したい場合などは、#{}を使ってエスケープするといい。

.rgb {
    color: unquote("text");
    content: "blue: #{blue(#fff)}";
}

では1つずつ順番に見ていく。

RGBカラー (RGB Functions)

rgb($red, $green, $blue)

rgb値を指定して16進数カラーコードまたはカラー名を出力する。

.rgb {
    color: rgb(30, 30, 30); // #1e1e1e
}

rgba($red, $green, $blue, $alpha)

rgb値とalpha値を指定して透明度を指定。rgba()の形式で出力される。
$alpha が1の場合、16進数カラーコードまたはカラー名を出力する。

.rgba {
    color: rgba(30, 30, 30, 0.5); // rgba(30, 30, 30, 0.5)
}

red($color)

CSSで指定することができるカラーコードからredの値を出力する。

.red {
    &:before {
        content: "red: #{red(#fff)}"; // red: 255
    }
}

green($color)

CSSで指定することができるカラーコードからgreenの値を出力する。

.green {
    &:before {
        content: "green: #{green(#fff)}"; // green: 255
    }
}

blue($color)

CSSで指定することができるカラーコードからblueの値を出力する。

.blue {
    &:before {
        content: "blue: #{blue(#fff)}"; // blue: 255
    }
}

mix($color1, $color2, [$weight])

2つのカラーコードから中間色を抽出する。
$weight は中間値。0〜100％で指定。

.mix {
    color: mix(white, black); // #7f7f7f
}

HSLカラー (HSL Functions)

hsl($hue, $saturation, $lightness)

hsl値を指定して16進数カラーコードまたはカラー名を出力する。

.hsl {
    color: hsl(292, 89, 51); // #d413f1
}

hsla($hue, $saturation, $lightness, $alpha)

hsl値とalpha値を指定して透明度を指定。rgba()の形式で出力される。
$alpha が1の場合、16進数カラーコードまたはカラー名を出力する。

.hsla {
    color: hsla(292, 89, 51, .5); // rgba(212, 19, 241, 0.5)
}

hue($color)

CSSで指定することができるカラーコードからhue(色相)の値を出力する。

.hue {
    &:before {
        content: "hue: #{hue(blue)}"; // hue: 240deg
    }
}

saturation($color)

CSSで指定することができるカラーコードからsaturation(彩度)の値を出力する。

.saturation {
    &:before {
        content: "saturation: #{saturation(blue)}"; // saturation: 100%
    }
}

lightness($color)

CSSで指定することができるカラーコードからlightness(明度)の値を出力する。

.lightness {
    &:before {
        content: "lightness: #{lightness(blue)}"; // lightness: 50%
    }
}

adjust-hue($color, $degrees)

色相値の調整。色相環の度数($degrees)をdegで指定。マイナス値の指定も可。

.adjust-hue {
    color: adjust-hue(hsl(292, 89, 51), -60deg); // #1330f1
}

lighten($color, $amount)

輝度を明るくする。$amountを%で指定。

.lighten {
    color: lighten($color, 30%); // #9999ff
}

darken($color, $amount)

輝度を暗くする。$amountを%で指定。

.darken {
    color: darken($color, 30%); // #000066
}

saturate($color, $amount)

彩度を上げる。$amountを%で指定。

.saturate {
    color: saturate($color, 20%); // blue
}

desaturate($color, $amount)

彩度を下げる。$amountを%で指定。

.desaturate {
    color: desaturate($color, 20%); // #1919e6
}

grayscale($color)

グレースケールに変換する。desaturate(color, 100%)と同じ効果になる。

.grayscale {
    color: grayscale($color); // gray
}

complement($color)

色相の補色を返す(色相環の反対色)。adjust-hue(color, 180deg)と同じ効果になる。

.complement {
    color: complement($color); // yellow
}

invert($color)

色を反転させる。赤・緑・青の値を反転するが、透明度はそのまま。

.invert {
    color: invert($color); // yellow
}

透明度 (Opacity Functions)

alpha($color) / opacity($color)

透明度を返す。色に透明度の指定がない場合は常に1となる。
alpha()はMicrosoftの独自フィルタ構文 alpha(opacity=20) をサポートしている。

.alpha {
    color: alpha($color); // 1
}
.opacity {
    color: opacity($color); // 1
}

rgba($color, $alpha)

RGBカラーの項と同じ。

.rgba {
    color: rgba($color, 0.5); // rgba(0, 0, 0, 0.5)
}

opacify($color, $amount) / fade-in($color, $amount)

透明度を上げる。
$amount に0〜1の間で指定。指定された数値が透明度に加算される。

.opacify {
    color: opacify($color, 0.25); // blue
}
.fade-in {
    color: fade-in($color, 0.25); // blue
}

transparentize($color, $amount) / fade-out($color, $amount)

透明度を下げる。
$amount に0〜1の間で指定。指定された数値が透明度から減算される。

.trasparentize {
    color: transparentize($color, 0.5); // rgba(0, 0, 255, 0.5)
}
.fade-out {
    color: fade-out($color, 0.5); // rgba(0, 0, 255, 0.5)
}

その他の色関係 (Other Color Functions)

adjust-color($color, [$red], [$green], [$blue], [$hue], [$saturation], [$lightness], [$alpha])

赤、緑、青、色相、彩度、明度、および透明度を変更する。
元の色から加算・減算される。 RGBの数値とHSLの数値を同時に指定することはできない。

.adjust-color {
    color: adjust-color($color, $red: 10, $blue: -130); // #0a007d
}

scale-color($color, [$red], [$green], [$blue], [$saturation], [$lightness], [$alpha])

流動的に色数値を変更する。
全て%指定。

.scale-color {
    color: scale-color($color, $red: 10%, $blue: -30%); // #1900b2
}

change-color($color, [$red], [$green], [$blue], [$hue], [$saturation], [$lightness], [$alpha])

色の数値を変更する。指定された数値は加算・減算ではなく、置換される。

.change-color {
    color: change-color($color, $red: 10, $green: 10, $blue: 0, $alpha: 0.5); // rgba(10, 10, 0, 0.5)
}

ie-hex-str($color)

IEのフィルタで使用する為の透明度を付与したカラーコードに変換する。

.ie-hex-str {
   -ms-filter: "progid:DXImageTransform.Microsoft.gradient(startColorStr='#{ie-hex-str($color)}',EndColorStr='#{ie-hex-str($color)}')";
   filter: progid:DXImageTransform.Microsoft.gradient(startColorStr='#{ie-hex-str($color)}',EndColorStr='#{ie-hex-str($color)}');
   // ##FF0000FF
}

文字列 (String Functions)

unquote($string)

文字列の引用符を取り除く。

.unquote {
    &:before {
        content: "#{unquote($string)}"; // string
    }
}

quote($string)

文字列を引用符で囲う。

.quote {
    &:before {
        content: "#{quote(string)}"; // "string"
    }
}

str-length($string)

文字数を返す。

.str-length {
    &:before {
        content: "#{str-length($string)}"; // 6
    }
}

str-insert($string, $insert, $index)

文字列に指定された文字($insert)を挿入する。
$indexに数値を指定すると挿入する位置を指定できる。

.str-insert {
    &:before {
        content: "#{str-insert($string, '(str)', 4)}"; // str(str)ing
    }
}

str-index($string, $substring)

指定した文字列($substring)が最初に出現する位置番号を返す。

.str-index {
    &:before {
        content: "#{str-index($string, tr)}"; // 2
    }
}

str-slice($string, $start-at, [$end-at])

文字列を部分的に取り出す。

.str-slice {
    &:before {
        content: "#{str-slice($string, 3)}"; // ring
    }
}

to-upper-case($string)

文字列を大文字に変換する。

.to-upper-case {
    &:before {
        content: "#{to-upper-case($string)}"; // STRING
    }
}

to-lower-case($string)

文字列を小文字に変換する。

.to-lower-case {
    &:before {
        content: "#{to-lower-case($string)}"; // string
    }
}

数値 (Number Functions)

percentage($number)

単位の無い数値を%に変換する。

.percentage {
    width: percentage($number / 100); // 50%
}

round($number)

小数点以下を四捨五入する。

.round {
    width: round(510.4px); // 510px
}

ceil($number)

小数点以下を切り上げる。

.ceil {
    width: ceil(510.4px); // 511px
}

floor($number)

小数点以下を切り下げる。

.floor {
    width: floor(510.4px); // 510px
}

abs($number)

数値の絶対値を返す。

.abs {
    width: abs(-100px); // 100px
}

min($numbers...)

数値の最小値を返す。

.min {
    width: min(100px, 30px, 500px); // 30px
}

max($numbers...)

数値の最大値を返す。

.max {
    width: max(100px, 30px, 500px); // 500px
}

random([$limit])

0〜1のランダムな数値を返す。

.random {
    opacity: random(); // 0.15317
}

配列 (List Functions)

$list: list1 list2 list3;

length($list)

配列の長さ(値の数)を返す。

.length {
    &:before {
        content: "#{length($list)}"; // 3
    }
}

nth($list, $n)

指定した順番($n)の要素を取り出す。

.nth {
    &:before {
        content: "#{nth($list, 1)}"; // list1
    }
}

set-nth($list, $n, $value)

指定した順番($n)の要素を変更する。

.set-nth {
    &:before {
        content: "#{nth(set-nth($list, $n: 2, $value: list10), 2)}"; // list10
    }
}

join($list1, $list2, [$separator])

2つの配列を連結する。
デフォルトの連結文字はスペース。

.join {
    &:before {
        content: "#{join($list, $list, 'comma')}"; // list1, list2, list3, list1, list2, list3
    }
}

append($list1, $val, [$separator])

配列の最後に値($val)を追加する。
デフォルトの連結文字はスペース。

.append {
    &:before {
        content: "#{append($list, list4 list5 list6)}"; // list1 list2 list3 list4 list5 list6
    }
}

zip($lists...)

多次元配列を新しい多次元配列に組み替える。

.zip {
    $properties: zip(1px 1px 3px, solid dashed solid, red green blue);
    &:before {
        content: "#{$properties}"; // 1px solid red, 1px dashed green, 3px solid blue
    }
}

index($list, $value)

指定された値($value)の位置番号を返す。

.index {
    &:before {
        content: "#{index($list, list2)}"; // 2
    }
}

list-separator(#limit)

配列の区切り文字を返す。(space か comma)

.list-separator {
    &:before {
        content: "#{list-separator($list)}"; // space
    }
}

マップ構造体 (Map Functions)

Sass 3.3で追加された機能。
JavaScriptのオブジェクトのようなキーと値が対になった構造のデータタイプ。

$map: (
    string: 'text',
    number: 10,
    pixel: 10px,
    color: #ccc,
    bool: true,
    obj: null,
    list: foo bar baz,
    nest: (
        some: 'thing',
    ),
);

map-get($map, $key)

指定したキー($key)の値を取り出す。

.map-get {
    margin-right: map-get($map, pixel); // 10px
    color: map-get($map, color); // #ccc

    &:after {
        content: "#{map-get(map-get($map, nest), some)}" // thing
    }
}

map-merge($map1, $map2)

2つのマップを連結する。
連想配列(多重階層)のマップがある場合、nullが返る。

.map-merge {
    $map1: ( key1: value1, key2: value2, key3: value3);
    $map2: ( key4: value4, key5: value5);
    $new-map: map-merge($map1, $map2);

    &:before {
        content: "#{map-get($new-map, key5)}"; // value5
    }
}

map-remove($map, $keys...)

指定したキー($keys)を削除する。

.map-remove {
    $remove: map-remove(("foo": 1, "bar": 2, "baz": 3), "bar");
    &:before {
        content: "#{map-get($remove, "bar")}"; // null
    }
}

map-keys($map)

マップの全てのキー名を返す。

.map-keys {
    &:before {
        content: "#{map-keys($map)}"; // string, number, pixel, color, bool, obj, list, nest
    }
}

map-values($map)

マップの全ての値を返す。

.map-values {
    $map-number: (key1: 1, key2: 2, key3: 3, key4: 4, key5: 5, key6: 6);
    &:before {
        content: "#{map-values($map-number)}"; // 1, 2, 3, 4, 5, 6
    }
}

map-has-key($map, $key)

指定したキー($key)が含まれているかチェックする。
true もしくはfalse が返る。

.map-has-key {
    &:before {
        content: "#{map-has-key($map, string)}"; // true
    }
}

keywords($args)

可変引数を取る関数に渡されるキーワードを返す。

@mixin foo($args...) {
    @debug keywords($args); //=> (arg1: val, arg2: val)
}

@include foo($arg1: val, $arg2: val);

CSSセレクタ (Selector Functions)

selector-nest($selectors...)

指定したセレクタ名を入れ子にさせた、新しいセレクタを返す。

.selector-nest {
    &:before {
        content: "#{selector-nest(".foo", ".bar", ".baz")}"; // .foo .bar .baz
    }
}

selector-append($selectors...)

指定したセレクタ名を連結した、新しいセレクタを返す。

.selector-append {
    &:before {
        content: "#{selector-append(".foo", ".bar", ".baz")}"; // .foo.bar.baz
    }
}

selector-extend($selector, $extendee, $extender)

$selector の中にある $extendee を取り除いたセレクタを $extender に extendする。

.selector-extend {
    &:before {
        content: "#{selector-extend(".a .b", ".b", ".foo .bar")}"; // .a .b, .a .foo .bar, .foo .a .bar
    }
}

selector-replace($selector, $original, $replacement)

指定したセレクタ内にあるセレクタ名($original)を$replacement で置換する。

.selector-replace {
    &:before {
        content: "#{selector-replace(".clearfix.header.is-fixed", ".is-fixed", ".is-static")}"; // .clearfix.header.is-static
    }
}

selector-unify($selector1, $selector2)

指定した2つのセレクタにマッチした要素だけに一致するセレクタを生成。
セレクタが存在しない場合はnullを返す。

.selector-unify {
    &:before {
        content: "#{selector-unify(".a .b", ".x .y")}"; // .a .x .b.y, .x .a .b.y
        content: "#{selector-unify(".a.b.f", ".b.c")}"; // .a.b.f.c
    }
}

is-superselector($super, $sub)

$super は $sub の継承元セレクタであるかどうかを判定する。
しかし、挙動としては $super が $sub に含まれているかどうかになっている。

.is-superselector {
    &:before {
        content: "#{is-superselector(".foo", ".foo.bar")}"; // true
        content: "#{is-superselector(".foo.bar", ".foo")}"; // false
        content: "#{is-superselector(".bar", ".foo .bar")}"; // true
    }
}

simple-selectors($selector)

連結されたセレクタを分解する。

.simple-selectors {
    &:before {
        content: "#{simple-selectors("div#content.foo.bar.baz.clearfix")}"; // div, #content, .foo, .bar, .baz, .clearfix
    }
}

selector-parse($selector)

入力されたセレクタを配列で返す。

.selector-parse {
    &:before {
        content: "#{selector-parse(".foo .bar, .baz .bang, .test:hover .test:after, .test.testest")}"; // .foo .bar, .baz .bang, .test:hover .test:after, .test.testest
    }
}

チェック・検出 (Introspection Functions)

feature-exists($feature)

特定の機能がSassのランタイムに存在するか判定する。

global-variable-shadowing indicates that a local variable will shadow a global variable unless !global is used.
extend-selector-pseudoclass indicates that @extend will reach into selector pseudoclasses like :not.
units-level-3 indicates full support for unit arithmetic using units defined in the Values and Units Level 3 spec.
at-error indicates that the Sass @error directive is supported.

.feature-exists {
    &:before {
        content: "#{feature-exists(extend-selector-pseudoclass)}"; // true
    }
}

variable-exists($name)

現在のスコープに変数$nameが定義されているか判定する。
$name は$を含めない点に注意。

.variable-exists {
    $var: 'variable';
    &:before {
        content: "#{variable-exists(var)}"; // true
    }
}

global-variable-exists($name)

グローバルスコープに変数$nameが定義されているか判定する。
$name は$を含めない点に注意。

.global-variable-exists {
    &:before {
        content: "#{global-variable-exists(color)}"; // true
    }
}

function-exists($name)

関数$nameが定義されているか判定する。

.function-exists {
    &:before {
        content: "#{function-exists(lighten)}"; // true
        content: "#{function-exists(random)}"; // true
    }
}

mixin-exists($name)

ミックスイン$nameが定義されているか判定する。

@mixin red-text { color: red; }

.mixin-exists {
    &:before {
        content: "#{mixin-exists(red-text)}"; // true
    }
}

inspect($value)

Sassで使われる値の単位として正しいかどうかを判定し、その文字列を返す。

.inspect {
    &:before {
        content: "#{inspect(10px)}"; // 10px
    }
}

type-of($value)

値のデータ型を返す。返される型の名前は引用符は無し。
string, number, bool, colorなど。

.type-of {
    &:before {
        @if type-of(true) == bool { // bool
            content: "type-of(true)";
        }
    }
}

unit($number)

指定した数値の単位の単位を文字列として返す。
複雑な単位はアルファベット順にソートされる。

.unit {
    &:before {
        content: "#{unit(100px / 3em)}"; // px/em
    }
}

unitless($number)

指定した数値が単位を持っているかどうか判定する。
単位がなければtrueが返る。

.unitless {
    &:before {
        content: "#{unitless(100)}"; // true
        content: "#{unitless(100px)}"; // false
    }
}

comparable($number1, $number2)

指定した2つの数字が加算、減算、比較できるかどうか判定する。

.comparable {
    &:before {
        content: "#{comparable(100px, 3px)}"; // true
        content: "#{comparable(100ex, 3em)}"; // false
    }
}

call($name, $args...)

動的にSassの関数を実行する。

.call {
    color: call('rgb', 10, 100, 255); // #0a64ff
}

その他 (Miscellaneous Functions)

if($condition, $if-true, $if-false)

$condition が真か否かに応じて2つのいずれかの値を返す。
@if とは別に、条件分岐を関数で。

.if {
    color: if(global-variable-exists(color), $color, red); // blue
}

unique-id()

ユニークIDの生成。

.unique-id {
    &:before {
        content: "#{unique-id()}"; // ucafwaqvm
    }
}

まとめ

こうしてみると、ライブラリやCSSフレームワークを作る際には是非覚えておきたい機能が多いと感じる。
これらは自由自在に使えることに越したことはないが、 Sassにはこうゆう機能が備わっていることを理解することも重要だ。

※ちなみに:beforeのcontentプロパティに指定したのはログ用途である。

DEMO

Codepenにデモを上げた。これをいじりながら試してみるといい。
Demo

参考

【公式ドキュメント】 Module: Sass::Script::Functions — Sass Documentation