stylus中文版参考文档之内置方法(Built-in Functions)

red(color)

返回color中的红色比重。

red(#c00)
// => 204

green(color)

返回color中的绿色比重。

green(#0c0)
// => 204

blue(color)

返回color中的蓝色比重。

red(#00c)
// => 204

alpha(color)

返回color中的透明度比重。

alpha(#fff)
// => 1

alpha(rgba(0,0,0,0.3))
// => 0.3

dark(color)

检查color是否是暗色。

dark(black)
// => true

dark(#005716)
// => true

dark(white)
// => false

light(color)

检查color是否是亮色。

light(black)
// => false

light(white)
// => true

light(#00FF40)
// => true

hue(color)

返回给定color的色调。

hue(hsla(50deg, 100%, 80%))
// => 50deg

saturation(color)

返回给定color的饱和度。

saturation(hsla(50deg, 100%, 80%))
// => 100%

lightness(color)

返回给定color的亮度。

lightness(hsla(50deg, 100%, 80%))
// => 80%

push(expr, args…)

后面推送给定的args给expr.

nums = 1 2
push(nums, 3, 4, 5)

nums
// => 1 2 3 4 5

别名为append().

unshift(expr, args…)

起始位置插入给定的args给expr.

nums = 4 5
unshift(nums, 3, 2, 1)

nums
// => 1 2 3 4 5

别名为prepend().

keys(pairs)

返回给定pairs中的键。

pairs = (one 1) (two 2) (three 3)
keys(pairs)
// => one two three

values(pairs)

返回给定pairs中的值。

pairs = (one 1) (two 2) (three 3)
values(pairs)
// => 1 2 3

typeof(node)

字符串形式返回node类型。

type(12)
// => 'unit'

typeof(12)
// => 'unit'

typeof(#fff)
// => 'rgba'

type-of(#fff)
// => 'rgba'

别名有type-of和type.

unit(unit[, type])

返回unit类型的字符串或空字符串，或者赋予type值而无需单位转换。

unit(10)
// => ''

unit(15in)
// => 'in'

unit(15%, 'px')
// => 15px

unit(15%, px)
// => 15px

match(pattern, string)

检测string是否匹配给定的pattern.

match('^foo(bar)?', foo)
match('^foo(bar)?', foobar)
// => true

match('^foo(bar)?', 'foo')
match('^foo(bar)?', 'foobar')
// => true

match('^foo(bar)?', 'bar')
// => false

abs(unit)

绝对值。

abs(-5px)
// => 5px

abs(5px)
// => 5px

ceil(unit)

向上取整。

ceil(5.5in)
// => 6in

floor(unit)

向下取整。

floor(5.6px)
// => 5px

round(unit)

四舍五入取整。

round(5.5px)
// => 6px

round(5.4px)
// => 5px

min(a, b)

取较小值。

min(1, 5)
// => 1

max(a, b)

取较大值。

max(1, 5)
// => 5

even(unit)

是否为偶数。

even(6px)
// => true

add(unit)

是否为奇数。

odd(5mm)
// => true

sum(nums)

求和。

sum(1 2 3)
// => 6

avg(nums)

求平均数。

avg(1 2 3)
// => 2

join(delim, vals…)

给定vals使用delim连接。

join(' ', 1 2 3)
// => "1 2 3"

join(',', 1 2 3)
// => "1,2,3"

join(', ', foo bar baz)
// => "foo, bar, baz"

join(', ', foo, bar, baz)
// => "foo, bar, baz"

join(', ', 1 2, 3 4, 5 6)
// => "1 2, 3 4, 5 6"

hsla(color | h,s,l,a)

转换给定color为HSLA节点，或h,s,l,a比重值。

hslaa(10deg, 50%, 30%, 0.5)
// => HSLA

hslaa(#ffcc00)
// => HSLA

hsla(color | h,s,l)

转换给定color为HSLA节点，或h,s,l比重值。

hsla(10, 50, 30)
// => HSLA

hsla(#ffcc00)
// => HSLA

rgba(color | r,g,b,a)

从r,g,b,a通道返回RGBA, 或提供color来调整透明度。

rgba(255,0,0,0.5)
// => rgba(255,0,0,0.5)

rgba(255,0,0,1)
// => #ff0000

rgba(#ffcc00, 0.5)
// rgba(255,204,0,0.5)

另外，stylus支持#rgba以及#rrggbbaa符号。

#fc08
// => rgba(255,204,0,0.5)

#ffcc00ee
// => rgba(255,204,0,0.9)

rgb(color | r,g,b)

从r,g,b通道返回RGBA或生成一个RGBA节点。

rgb(255,204,0)
// => #ffcc00

rgb(#fff)
// => #fff

lighten(color, amount)

给定color增亮amount值。该方法单位敏感，例如，支持百分比，如下：

lighten(#2c2c2c, 30)
// => #787878

lighten(#2c2c2c, 30%)
// => #393939

darken(color, amount)

给定color变暗amount值。该方法单位敏感，例如，支持百分比，如下：

darken(#D62828, 30)
// => #551010

darken(#D62828, 30%)
// => #961c1c

desaturate(color, amount)

给定color饱和度减小amount.

desaturate(#f00, 40%)
// => #c33

saturate(color, amount)

给定color饱和度增加amount.

saturate(#c33, 40%)
// => #f00

invert(color)

颜色反相。红绿蓝颜色反转，透明度不变。

invert(#d62828)
// => #29d7d7

unquote(str | ident)

给定str引号去除，返回Literal节点。

unquote("sans-serif")
// => sans-serif

unquote(sans-serif)
// => sans-serif

unquote('1px / 2px')
// => 1px / 2px

s(fmt, …)

s()方法类似于unquote()，不过后者返回的是Literal节点，而这里起接受一个格式化的字符串，非常像C语言的sprintf(). 目前，唯一标识符是%s.

s('bar()');
// => bar()

s('bar(%s)', 'baz');
// => bar("baz")

s('bar(%s)', baz);
// => bar(baz)

s('bar(%s)', 15px);
// => bar(15px)

s('rgba(%s, %s, %s, 0.5)', 255, 100, 50);
// => rgba(255, 100, 50, 0.5)

s('bar(%Z)', 15px);
// => bar(%Z)

s('bar(%s, %s)', 15px);
// => bar(15px, null)

为表现一致检测这个%字符串操作符。

operate(op, left, right)

在left和right操作对象上执行给定的op.

op = '+'
operate(op, 15, 5)
// => 20

length([expr])

括号表达式扮演元组，length()方法返回该表达式的长度。

length((1 2 3 4))
// => 4

length((1 2))
// => 2

length((1))
// => 1

length(())
// => 0

length(1 2 3)
// => 3

length(1)
// => 1

length()
// => 0

warn(msg)

使用给定的error警告，并不退出。

warn("oh noes!")

error(msg)

伴随着给定的错误msg退出。

add(a, b)
  unless a is a 'unit' and b is a 'unit'
    error('add() expects units')
  a + b

last(expr)

返回给定expr的最后一个值。

nums = 1 2 3
last(nums)
last(1 2 3)
// => 3

list = (one 1) (two 2) (three 3)
last(list)
// => (three 3)

p(expr)

检查给定的expr.

fonts = Arial, sans-serif
p('test')
p(123)
p((1 2 3))
p(fonts)
p(#fff)
p(rgba(0,0,0,0.2))

add(a, b)
  a + b

p(add)

标准输出：

inspect: "test"
inspect: 123
inspect: 1 2 3
inspect: Arial, sans-serif
inspect: #fff
inspect: rgba(0,0,0,0.2)
inspect: add(a, b)

opposite-position(positions)

返回给定positions相反内容。

opposite-position(right)
// => left

opposite-position(top left)
// => bottom right

opposite-position('top' 'left')
// => bottom right

image-size(path)

返回指定path图片的width和height. 向上查找路径的方法和@import一样，paths设置的时候改变。

width(img)
  return image-size(img)[0]

height(img)
  return image-size(img)[1]

image-size('tux.png')
// => 405px 250px

image-size('tux.png')[0] == width('tux.png')
// => true

add-property(name, expr)

使用给定的expr为最近的块域添加属性name。

例如：

something()
  add-property('bar', 1 2 3)
  s('bar')

body
  foo: something()

真实面目：

body {
  bar: 1 2 3;
  foo: bar;
}

接下来，“神奇”的current-property局部变量将大放异彩，这个变量自动提供给函数体，且包含当前属性名和值的表达式。

例如，我们使用p()检查这个局部变量，我们可以得到：

p(current-property)
// => "foo" (foo __CALL__ bar baz)

p(current-property[0])
// => "foo"

p(current-property[1])
// => foo __CALL__ bar baz

使用current-property我们可以让例子走得更远点，使用新值复制该属性，且确保功能的条件仅在属性值中使用。

something(n)
  if current-property
    add-property(current-property[0], s('-webkit-something(%s)', n))
    add-property(current-property[0], s('-moz-something(%s)', n))
    s('something(%s)', n)
  else
    error('something() must be used within a property')

body {
  foo: something(15px) bar;
}

生成为：

body {
  foo: -webkit-something(15px);
  foo: -moz-something(15px);
  foo: something(15px) bar;
}

如果你注意上面这个例子，会发现bar只在一开始调用的时候出现，因为我们返回something(15px), 其仍留在表达式里，然而，其他人并不重视其余的表达式。

更强大的解决方案如下，定义一个名为replace()的函数，其克隆表达式，以防止出现变化，用另外一个替换表达式的字符串值，并返回克隆的表达式。然后我们继续在表达式中替换__CALL__，表示循环调用something().

replace(expr, str, val)
  expr = clone(expr)
  for e, i in expr
    if str == e
      expr[i] = val
  expr

something(n)
  if current-property
    val = current-property[1]
    webkit = replace(val, '__CALL__', s('-webkit-something(%s)', n))
    moz = replace(val, '__CALL__', s('-moz-something(%s)', n))
    add-property(current-property[0], webkit)
    add-property(current-property[0], moz)
    s('something(%s)', n)
  else
    error('something() 必须在属性中使用')

生成：

body {
  foo: foo -webkit-something(5px) bar baz;
  foo: foo -moz-something(5px) bar baz;
  foo: foo something(5px) bar baz;
}

无论是内部调用的使用还是调用的位置上，我们实现的方法现在是完全透明的了。这个强大概念有助于在一些私有属性使用时调用，例如渐变。

未定义方法

未定义方法一字面量形式输出。例如，我们可以在CSS中调用rgba-stop(50%, #fff), 其会按照你所期望的显示，我们也可以使用这些内部助手。

下面这个例子中我们简单定义了方法stop(), 其返回了字面上rgba-stop()调用。

stop(pos, rgba)
  rgba-stop(pos, rgba)

stop(50%, orange)
// => rgba-stop(50%, #ffa500)