Stylus 中文网

Appearance

Return to top
On this page

内置函数

¥Built-in Functions

颜色函数

¥Color Functions

red(color[, value])

返回给定 color 的红色分量，或将红色分量设置为可选的第二个 value 参数。

¥Return the red component of the given color, or set the red component to the optional second value argument.

red(#c00)
// => 204

red(#000, 255)
// => #f00

red(#c00)
// => 204

red(#000, 255)
// => #f00

green(color[, value])

返回给定 color 的绿色分量，或将绿色分量设置为可选的第二个 value 参数。

¥Return the green component of the given color, or set the green component to the optional second value argument.

green(#0c0)
// => 204

green(#000, 255)
// => #0f0

green(#0c0)
// => 204

green(#000, 255)
// => #0f0

blue(color[, value])

返回给定 color 的蓝色分量，或将蓝色分量设置为可选的第二个 value 参数。

¥Return the blue component of the given color, or set the blue component to the optional second value argument.

blue(#00c)
// => 204

blue(#000, 255)
// => #00f

blue(#00c)
// => 204

blue(#000, 255)
// => #00f

alpha(color[, value])

返回给定 color 的 alpha 分量，或将 alpha 分量设置为可选的第二个 value 参数。

¥Return the alpha component of the given color, or set the alpha component to the optional second value argument.

alpha(#fff)
// => 1

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

alpha(#fff, 0.5)
// => rgba(255,255,255,0.5)

alpha(#fff)
// => 1

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

alpha(#fff, 0.5)
// => rgba(255,255,255,0.5)

dark(color)

检查 color 是否为暗：

¥Check if color is dark:

dark(black)
// => true

dark(#005716)
// => true

dark(white)
// => false

dark(black)
// => true

dark(#005716)
// => true

dark(white)
// => false

light(color)

检查 color 是否亮：

¥Check if color is light:

light(black)
// => false

light(white)
// => true

light(#00FF40)
// => true

light(black)
// => false

light(white)
// => true

light(#00FF40)
// => true

hue(color[, value])

返回给定 color 的色调，或将色调分量设置为可选的第二个 value 参数。

¥Return the hue of the given color, or set the hue component to the optional second value argument.

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

hue(#00c, 90deg)
// => #6c0

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

hue(#00c, 90deg)
// => #6c0

saturation(color[, value])

返回给定 color 的饱和度，或将饱和度分量设置为可选的第二个 value 参数。

¥Return the saturation of the given color, or set the saturation component to the optional second value argument.

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

saturation(#00c, 50%)
// => #339

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

saturation(#00c, 50%)
// => #339

lightness(color[, value])

返回给定 color 的亮度，或将亮度分量设置为可选的第二个 value 参数。

¥Return the lightness of the given color, or set the lightness component to the optional second value argument.

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

lightness(#00c, 80%)
// => #99f

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

lightness(#00c, 80%)
// => #99f

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

将给定的 color 转换为 HSLA 节点，或 h、s、l、a 分量值。

¥Convert the given color to an HSLA node, or h,s,l,a component values.

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

hsla(#ffcc00)
// => HSLA

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

hsla(#ffcc00)
// => HSLA

hsl(color | h,s,l)

将给定的 color 转换为 HSLA 节点，或 h、s、l、a 分量值。

¥Convert the given color to an HSLA node, or h,s,l,a component values.

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

hsl(#ffcc00)
// => HSLA

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

hsl(#ffcc00)
// => HSLA

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

从 r、g、b、a 通道返回 RGBA，或提供 color 来调整 alpha。

¥Return RGBA from the r,g,b,a channels, or provide a color to tweak the alpha.

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)

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 表示法：

¥Alternatively, Stylus supports the #rgba and #rrggbbaa notations as well:

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

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

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

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

rgb(color | r,g,b)

从 r、g、b 通道返回 RGBA 或投射到 RGBA 节点。

¥Return a RGBA from the r,g,b channels or cast to an RGBA node.

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

rgb(#fff)
// => #fff

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

rgb(#fff)
// => #fff

blend(top[, bottom])

使用正常混合将给定的 top 颜色混合到 bottom 颜色上。bottom 参数是可选的，默认为 #fff。

¥Blends the given top color over the bottom one using the normal blending. The bottom argument is optional, and defaults to #fff.

blend(rgba(#FFF, 0.5), #000)
// => #808080

blend(rgba(#FFDE00,.42), #19C261)
// => #7ace38

blend(rgba(lime, 0.5), rgba(red, 0.25))
// => rgba(128,128,0,0.625)

blend(rgba(#FFF, 0.5), #000)
// => #808080

blend(rgba(#FFDE00,.42), #19C261)
// => #7ace38

blend(rgba(lime, 0.5), rgba(red, 0.25))
// => rgba(128,128,0,0.625)

lighten(color, amount)

将给定的 color 减轻 amount。

¥Lighten the given color by amount.

该函数对单位敏感；它支持百分比，例如，如下所示：

¥This function is unit-sensitive; it supports percentages, for example, as shown here:

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

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

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

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

darken(color, amount)

用 amount 使给定的 color 变暗。

¥Darken the given color by amount.

该函数对单位敏感；它支持百分比，例如，如下所示：

¥This function is unit-sensitive; it supports percentages, for example, as shown here:

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

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

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

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

desaturate(color, amount)

通过 amount 降低给定 color 的饱和度。

¥Desaturate the given color by amount.

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

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

saturate(color, amount)

用 amount 使给定的 color 饱和。

¥Saturate the given color by amount.

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

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

complement(color)

给出互补色。相当于 180deg 旋转色调。

¥Gives the complementary color. Equivalent to spinning hue by 180deg.

complement(#fd0cc7)
// => #0cfd42

complement(#fd0cc7)
// => #0cfd42

invert(color)

反转颜色。红色、绿色和蓝色值反转。不透明度被保留。

¥Inverts the color. The red, green, and blue values are inverted. Opacity is left alone.

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

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

spin(color, amount)

按 amount 旋转给定 color 的色调。

¥Spins hue of the given color by amount.

spin(#ff0000, 90deg)
// => #80ff00

spin(#ff0000, 90deg)
// => #80ff00

grayscale(color)

给出给定颜色的灰度等效值。相当于 desaturate(color, 100%)。

¥Gives the grayscale equivalent of the given color. Equivalent to desaturate(color, 100%).

grayscale(#fd0cc7)
// => #0cfd42

grayscale(#fd0cc7)
// => #0cfd42

mix(color1, color2[, amount])

按给定的数量混合两种颜色。amount 是可选的，默认为 50%。

¥Mix two colors by a given amount. The amount is optional and is defaulted to 50%.

mix(#000, #fff, 30%)
// => #b2b2b2

mix(#000, #fff, 30%)
// => #b2b2b2

tint(color, amount)

将给定的颜色与白色混合。

¥Mix the given color with white.

tint(#fd0cc7,66%)
// => #feaceb

tint(#fd0cc7,66%)
// => #feaceb

shade(color, amount)

将给定的颜色与黑色混合。

¥Mix the given color with black.

shade(#fd0cc7,66%)
// => #560443

shade(#fd0cc7,66%)
// => #560443

luminosity(color)

返回给定 color 的 相对亮度。

¥Returns the relative luminance of the given color.

luminosity(white)
// => 1

luminosity(#000)
// => 0

luminosity(red)
// => 0.2126

luminosity(white)
// => 1

luminosity(#000)
// => 0

luminosity(red)
// => 0.2126

contrast(top[, bottom])

返回 top 和 bottom 颜色之间的 对比度 对象，基于 Lea Verou 的 script 底层“对比度”工具。

¥Returns the contrast ratio object between top and bottom colors, based on script underlying “contrast ratio” tool by Lea Verou.

第二个参数是可选的，默认为 #fff。

¥The second argument is optional and is defaulted to #fff.

返回对象中的主键是 ratio，只有当 bottom 颜色为透明时，它还有 min 和 max 值，与 ratio 不同。在这种情况下，error 还包含误差范围。

¥The main key in the returned object is ratio, it also have min and max values that are different from the ratio only when the bottom color is transparent. In that case the error also contains an error margin.

contrast(#000, #fff).ratio
// => 21
contrast(#000, rgba(#FFF, 0.5))
// => { "ratio": "13.15;", "error": "-7.85", "min": "5.3", "max": "21" }

contrast(#000, #fff).ratio
// => 21
contrast(#000, rgba(#FFF, 0.5))
// => { "ratio": "13.15;", "error": "-7.85", "min": "5.3", "max": "21" }

transparentify(top[, bottom, alpha])

返回给定 top 颜色的透明版本，就好像它是在给定 bottom 颜色上混合的（或者最接近它的颜色，如果可能的话）。

¥Returns the transparent version of the given top color, as if it was blend over the given bottom color (or the closest to it, if it is possible).

第二个参数是可选的，默认为 #fff。

¥The second argument is optional and is defaulted to #fff.

第三个参数是可选的，并覆盖自动检测到的 alpha。

¥The third argument is optional and overrides the autodetected alpha.

transparentify(#808080)
// => rgba(0,0,0,0.5)

transparentify(#414141, #000)
// => rgba(255,255,255,0.25)

transparentify(#91974C, #F34949, 0.5)
// => rgba(47,229,79,0.5)

transparentify(#808080)
// => rgba(0,0,0,0.5)

transparentify(#414141, #000)
// => rgba(255,255,255,0.25)

transparentify(#91974C, #F34949, 0.5)
// => rgba(47,229,79,0.5)

路径函数

¥Path Functions

basename(path[, ext])

返回 path 的基本名称，（可选）删除 ext 扩展名。

¥Returns the basename of path, (optionally) with ext extension removed.

basename('images/foo.png')
// => "foo.png"

basename('images/foo.png', '.png')
// => "foo"

basename('images/foo.png')
// => "foo.png"

basename('images/foo.png', '.png')
// => "foo"

dirname(path)

返回 path 的目录名。

¥Returns the dirname of path.

dirname('images/foo.png')
// => "images"

dirname('images/foo.png')
// => "images"

extname(path)

返回 path 的文件扩展名（包括点）。

¥Returns the filename extension of path including the dot.

extname('images/foo.png')
// => ".png"

extname('images/foo.png')
// => ".png"

pathjoin(...)

执行路径连接。

¥Peform a path join.

pathjoin('images', 'foo.png')
// => "images/foo.png"

path = 'images/foo.png'
ext = extname(path)
pathjoin(dirname(path), basename(path, ext) + _thumb + ext)
// => 'images/foo_thumb.png'

pathjoin('images', 'foo.png')
// => "images/foo.png"

path = 'images/foo.png'
ext = extname(path)
pathjoin(dirname(path), basename(path, ext) + _thumb + ext)
// => 'images/foo_thumb.png'

列表/哈希函数

¥List / Hash Functions

push(expr, args...)

将给定的 args 推送到 expr。

¥Push the given args to expr.

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

nums
// => 1 2 3 4 5

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

nums
// => 1 2 3 4 5

别名为 append()。

¥Aliased as append().

pop(expr)

从 expr 中弹出一个值。

¥Pop a value from expr.

nums = 4 5 3 2 1
num = pop(nums)

nums
// => 4 5 3 2
num
// => 1

nums = 4 5 3 2 1
num = pop(nums)

nums
// => 4 5 3 2
num
// => 1

shift(expr)

从 expr 移动一个元素。

¥Shift an element from expr.

nums = 4 5 3 2 1
num = shift(nums)

nums
// => 5 3 2 1
num
// => 4

nums = 4 5 3 2 1
num = shift(nums)

nums
// => 5 3 2 1
num
// => 4

unshift(expr, args...)

将给定的 args 取消移动到 expr。

¥Unshift the given args to expr.

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

nums
// => 1 2 3 4 5

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

nums
// => 1 2 3 4 5

别名为 prepend()。

¥Aliased as prepend().

index(list, value)

返回 list 中 value 的（从零开始的）索引。

¥Returns the (zero-based) index of value within a list.

list = 1 2 3

index(list, 2)
// => 1

index(1px solid red, red)
// => 2

list = 1 2 3

index(list, 2)
// => 1

index(1px solid red, red)
// => 2

keys(pairs)

返回给定 pairs 中的键：

¥Return keys in the given pairs:

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

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

values(pairs)

返回给定 pairs 中的值：

¥Return values in the given pairs:

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

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

list-separator(list)

返回给定 list 的分隔符。

¥Return the separator of the given list.

list1 = a b c
list-separator(list1)
// => ' '

list2 = a, b, c
list-separator(list2)
// => ','

list1 = a b c
list-separator(list1)
// => ' '

list2 = a, b, c
list-separator(list2)
// => ','

length([expr])

带括号的表达式可以充当元组，length() 函数返回此类表达式的长度。

¥Parenthesized expressions may act as tuples, the length() function returns the length of such expressions.

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

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

last(expr)

返回给定 expr 中的最后一个值：

¥Return the last value in the given expr:

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

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

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

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

单元函数

¥Unit Functions

typeof(node)

以字符串形式返回 node 的类型。

¥Return type of node as a string.

type(12)
// => 'unit'

typeof(12)
// => 'unit'

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

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

type(12)
// => 'unit'

typeof(12)
// => 'unit'

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

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

别名为 type-of 和 type。

¥Aliased as type-of and type.

unit(val[, type])

返回指示 val 类型的字符串或空字符串，或分配给定的 type 而不进行单位转换。

¥Return a string indicating the type of val or an empty string, or assign the given type without unit conversion.

unit(10)
// => ''

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

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

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

unit(10)
// => ''

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

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

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

percentage(num)

将 num 转换为百分比。

¥Convert a num to a percentage.

percentage(.5)
// => 50%

percentage(4 / 100)
// => 4%

percentage(.5)
// => 50%

percentage(4 / 100)
// => 4%

数学函数

¥Math Functions

abs(unit) 

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

abs(5px)
// => 5px

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

abs(5px)
// => 5px

ceil(unit) 

ceil(5.5in)
// => 6in

ceil(5.5in)
// => 6in

floor(unit) 

floor(5.6px)
// => 5px

floor(5.6px)
// => 5px

round(unit) 

round(5.5px)
// => 6px

round(5.4px)
// => 5px

round(5.5px)
// => 6px

round(5.4px)
// => 5px

注意：所有舍入函数都可以接受可选的 precision 参数 - 你可以传递要在句点后保存的位数：

¥Note: All rounding functions can accept optional precision argument — you can pass the number of digits you want to save after the period:

ceil(5.52px,1)
// => 5.6px

floor(5.57px,1)
// => 5.5px

round(5.52px,1)
// => 5.5px

ceil(5.52px,1)
// => 5.6px

floor(5.57px,1)
// => 5.5px

round(5.52px,1)
// => 5.5px

sin(angle)

返回给定 angle 的正弦值。如果角度以度单位给出，如 45deg，则将其视为度数，否则将其视为弧度。

¥Returns the value of sine for the given angle. If the angle is given as a degree unit, like 45deg, it is treated as a degree, otherwise it is treated as radians.

sin(30deg)
// => 0.5

sin(3*PI/4)
// => 0.707106781

sin(30deg)
// => 0.5

sin(3*PI/4)
// => 0.707106781

cos(angle)

返回给定 angle 的余弦值。如果角度以度单位给出，如 45deg，则将其视为度数，否则将其视为弧度。

¥Returns the value of cosine for the given angle. If the angle is given as a degree unit, like 45deg, it is treated as a degree, otherwise it is treated as radians.

cos(180deg)
// => -1

cos(180deg)
// => -1

tan(angle)

返回给定 angle 的正切值。如果角度以度单位给出，如 45deg，则将其视为度数，否则将其视为弧度。

¥Returns the value of tangent for the given angle. If the angle is given as a degree unit, like 45deg, it is treated as a degree, otherwise it is treated as radians.

tan(45deg)
// => 1

tan(90deg)
// => Infinity

tan(45deg)
// => 1

tan(90deg)
// => Infinity

min(a, b) 

min(1, 5)
// => 1

min(1, 5)
// => 1

max(a, b) 

max(1, 5)
// => 5

max(1, 5)
// => 5

even(unit) 

even(6px)
// => true

even(6px)
// => true

odd(unit) 

odd(5mm)
// => true

odd(5mm)
// => true

sum(nums) 

sum(1 2 3)
// => 6

sum(1 2 3)
// => 6

avg(nums) 

avg(1 2 3)
// => 2

avg(1 2 3)
// => 2

range(start, stop[, step])

返回给定 step 的从 start 到 stop（包含）的单位列表。

¥Returns a list of units from start to stop (included) by given step.

如果省略，则 step 参数默认为 1。不可能是 0。

¥The step argument defaults to 1 if omitted. It cannot be 0.

range(1, 6)
// equals to `1..6`
// 1 2 3 4 5 6

range(1, 6, 2)
// 1 3 5

range(-6, -1, 2)
// -6 -4 -2

range(1px, 3px, 0.5px)
// 1px 1.5px 2px 2.5px 3px

range(1, 6)
// equals to `1..6`
// 1 2 3 4 5 6

range(1, 6, 2)
// 1 3 5

range(-6, -1, 2)
// -6 -4 -2

range(1px, 3px, 0.5px)
// 1px 1.5px 2px 2.5px 3px

它最常用于 for 循环：

¥It is most often used in for loops:

for i in range(10px, 50px, 10)
  .col-{i}
    width: i

for i in range(10px, 50px, 10)
  .col-{i}
    width: i

产量：

¥Yields:

.col-10 {
  width: 10px;
}
.col-20 {
  width: 20px;
}
.col-30 {
  width: 30px;
}
.col-40 {
  width: 40px;
}
.col-50 {
  width: 50px;
}

.col-10 {
  width: 10px;
}
.col-20 {
  width: 20px;
}
.col-30 {
  width: 30px;
}
.col-40 {
  width: 40px;
}
.col-50 {
  width: 50px;
}

基数转换（数字，基数，宽度）

¥base-convert(num, base, width)

返回转换为提供的 base 的 Literal num，并用 width 零填充。

¥Returns a Literal num converted to the provided base, padded with width zeroes.

宽度默认为 2。

¥Width defaults to 2.

base-convert(1, 10, 3)
// => 001

base-convert(14, 16, 1)
// => e

base-convert(42, 2)
// => 101010

base-convert(1, 10, 3)
// => 001

base-convert(14, 16, 1)
// => e

base-convert(42, 2)
// => 101010

字符串函数

¥String Functions

match(pattern, string[, flags])

返回 string 中 pattern（正则表达式）的任何匹配项。

¥Returns any matches of pattern (regular expression) in string.

match('^(height|width)?([<>=]{1,})(.*)', 'height>=1024px')
// => 'height>=1024px' 'height' '>=' '1024px'

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

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

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

match('ain', 'The rain in SPAIN stays mainly in the plain')
// => 'ain'

match('ain', 'The rain in SPAIN stays mainly in the plain', g)
// => 'ain' 'ain' 'ain'

match('ain', 'The rain in SPAIN stays mainly in the plain', 'gi')
// => 'ain' 'AIN' 'ain' 'ain'

match('^(height|width)?([<>=]{1,})(.*)', 'height>=1024px')
// => 'height>=1024px' 'height' '>=' '1024px'

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

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

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

match('ain', 'The rain in SPAIN stays mainly in the plain')
// => 'ain'

match('ain', 'The rain in SPAIN stays mainly in the plain', g)
// => 'ain' 'ain' 'ain'

match('ain', 'The rain in SPAIN stays mainly in the plain', 'gi')
// => 'ain' 'AIN' 'ain' 'ain'

replace(pattern, replacement, val)

将所有 pattern 匹配项替换为 replacement 后，返回字符串 val。

¥Return the string val, after replacing with all pattern matches with replacement.

replace(i, e, 'griin')
// => 'green'

replace(i, e, griin)
// => #008000

replace(i, e, 'griin')
// => 'green'

replace(i, e, griin)
// => #008000

join(delim, vals...)

将给定的 vals 与 delim 连接。

¥Join the given vals with 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"

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"

split(delim, val)

split() 方法通过将字符串分成子字符串来将字符串或 ident 拆分为字符串列表。

¥The split() method splits a string or ident into a list of strings by separating the string into substrings.

split(_, bar1_bar2_bar3)
// => bar1 bar2 bar3

split(_, 'bar1_bar2_bar3')
// => 'bar1' 'bar2' 'bar3'

split(_, bar1_bar2_bar3)
// => bar1 bar2 bar3

split(_, 'bar1_bar2_bar3')
// => 'bar1' 'bar2' 'bar3'

substr(val, start, length)

substr() 方法返回字符串中从指定位置开始到指定字符数的字符。

¥The substr() method returns the characters in a string beginning at the specified location through the specified number of characters.

substr(ident, 1, 2)
// => de

substr('string', 1, 2)
// => 'tr'

val = dredd
substr(substr(val, 1), 0, 3)
// => #f00

substr(ident, 1, 2)
// => de

substr('string', 1, 2)
// => 'tr'

val = dredd
substr(substr(val, 1), 0, 3)
// => #f00

slice(val, start[, end])

slice() 方法提取字符串/列表的一部分并返回一个新的字符串/列表。

¥The slice() method extracts a section of a string/list and returns a new string/list.

slice('lorem' 'ipsum' 'dolor', 1, 2)
slice('lorem' 'ipsum' 'dolor', 1, -1)
// => 'ipsum'

slice('lorem ipsum', 1, 5)
// => 'orem'
slice(rredd, 1, -1)
// => #f00

slice(1px solid black, 1)
// => solid #000

slice('lorem' 'ipsum' 'dolor', 1, 2)
slice('lorem' 'ipsum' 'dolor', 1, -1)
// => 'ipsum'

slice('lorem ipsum', 1, 5)
// => 'orem'
slice(rredd, 1, -1)
// => #f00

slice(1px solid black, 1)
// => solid #000

unquote(str | ident)

取消引用给定的 str，并将其作为 Literal 节点返回。

¥Unquote the given str, and return it as a Literal node.

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

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

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

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

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

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

convert(str)

与 unquote() 类似，但尝试将给定的 str 转换为 Stylus 节点。

¥Like unquote() but tries to convert the given str to a Stylus node.

unit = convert('40px')
typeof(unit)
// => 'unit'

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

foo = convert('foo')
typeof(foo)
// => 'ident'

unit = convert('40px')
typeof(unit)
// => 'unit'

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

foo = convert('foo')
typeof(foo)
// => 'ident'

s(fmt, ...)

s() 函数与 unquote() 类似，它返回 Literal 节点。但是，它接受类似于 C 的 sprintf() 的格式字符串。

¥The s() function is similar to unquote(), in that it returns a Literal node. However, it accepts a format string similar to C's sprintf().

目前，唯一的说明符是 %s。

¥Currently, the only specifier is %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)

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)

查看 % 字符串运算符以了解等效行为。

¥Check out the % string operator for equivalent behaviour.

实用函数

¥Utility Functions

called-from 属性

¥called-from property

called-from 属性包含按相反顺序调用当前函数的函数列表（第一项是最深的函数）。

¥called-from property contains the list of the functions the current function was called from in reverse order (the first item is the deepest function).

foo()
  bar()

bar()
  baz()

baz()
  return called-from

foo()
// => bar foo

foo()
  bar()

bar()
  baz()

baz()
  return called-from

foo()
// => bar foo

current-media()

current-media() 函数返回当前块的 @media 规则的字符串（如果块上方没有 @media，则返回 ''）。

¥current-media() function returns the string of the current block's @media rule (or '' if there is no @media above the block).

@media only screen and (min-width: 1024px)
  current-media()
// => '@media (only screen and (min-width: (1024px)))'

@media only screen and (min-width: 1024px)
  current-media()
// => '@media (only screen and (min-width: (1024px)))'

+cache(keys...)

+cache 是一个非常强大的内置函数，允许你创建自己的“可缓存”mixin。

¥+cache is a really powerful built-in function that allows you to create your own “cachable” mixins.

“可缓存混合”是指在第一次调用时将其内容应用到给定的选择器，但在第二次调用时会使用相同的参数对第一次调用的选择器进行 @extend 操作。

¥A “cachable mixin” is one that would apply its contents to the given selector on the first call, but would @extend the first call's selector at the second call with the same params.

size($width, $height = $width)
  +cache('w' + $width)
    width: $width
  +cache('h' + $height)
    height: $height

.a
  size: 10px 20px
.b
  size: 10px 2em
.c
  size: 1px 2em

size($width, $height = $width)
  +cache('w' + $width)
    width: $width
  +cache('h' + $height)
    height: $height

.a
  size: 10px 20px
.b
  size: 10px 2em
.c
  size: 1px 2em

会屈服于

¥Would yield to

.a,
.b {
  width: 10px;
}
.a {
  height: 20px;
}
.b,
.c {
  height: 2em;
}
.c {
  width: 1px;
}

.a,
.b {
  width: 10px;
}
.a {
  height: 20px;
}
.b,
.c {
  height: 2em;
}
.c {
  width: 1px;
}

查看选择器如何按使用的属性分组在一起。

¥See how the selectors are grouped together by the used property.

+prefix-classes(prefix)

Stylus 附带了一个块 mixin prefix-classes，可用于为任何给定 Stylus 块内的类添加前缀。例如：

¥Stylus comes with a block mixin prefix-classes that can be used for prefixing the classes inside any given Stylus block. For example:

+prefix-classes('foo-')
  .bar
    width: 10px

+prefix-classes('foo-')
  .bar
    width: 10px

产量：

¥Yields:

.foo-bar {
  width: 10px;
}

.foo-bar {
  width: 10px;
}

lookup(name)

允许查找名为 name 的变量的值（以字符串形式传递）。如果变量未定义，则返回 null。

¥Allows looking up the value of a variable called name, passed as a string. Returns null if the variable is undefined.

当你需要获取具有动态生成名称的变量的值时很有用：

¥Useful when you need to get a value of a variable with dynamically generated name:

font-size-1 = 10px
font-size-2 = 20px
font-size-3 = 30px

for i in 1..3
  .text-{i}
    font-size: lookup('font-size-' + i)

font-size-1 = 10px
font-size-2 = 20px
font-size-3 = 30px

for i in 1..3
  .text-{i}
    font-size: lookup('font-size-' + i)

产量：

¥Yields:

.text-1 {
  font-size: 10px;
}
.text-2 {
  font-size: 20px;
}
.text-3 {
  font-size: 30px;
}

.text-1 {
  font-size: 10px;
}
.text-2 {
  font-size: 20px;
}
.text-3 {
  font-size: 30px;
}

define(name, expr[, global])

允许使用给定的 name 创建或覆盖变量，以字符串形式传递到当前作用域（如果 global 为 true，则为全局作用域）。

¥Allows to create or overwrite a variable with a given name, passed as a string, onto current scope (or global scope if global is true).

在需要在变量名称中进行插值的情况下，此 BIF 非常有用：

¥This BIF can be useful in those cases where you need interpolation in variable names:

prefix = 'border'
border = { color: #000, length: 1px, style: solid }

for prop, val in border
  define(prefix + '-' + prop, val)

body
  border: border-length border-style border-color

prefix = 'border'
border = { color: #000, length: 1px, style: solid }

for prop, val in border
  define(prefix + '-' + prop, val)

body
  border: border-length border-style border-color

产量：

¥yields:

body {
  border: 1px solid #000;
}

body {
  border: 1px solid #000;
}

operate(op, left, right)

对 left 和 right 操作数执行给定的 op：

¥Perform the given op on the left and right operands:

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

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

selector()

返回已编译的当前选择器或 &（如果在根级别调用）。

¥Returns the compiled current selector or & if called at root level.

.foo
  selector()
// => '.foo'

.foo
  &:hover
    selector()
// '.foo:hover'

.foo
  selector()
// => '.foo'

.foo
  &:hover
    selector()
// '.foo:hover'

selector-exists(selector)

如果 selector 存在则返回 true..

¥Returns true if selector exists..

.foo
  color red

  a
    font-size 12px

selector-exists('.foo') // true
selector-exists('.foo a') // true
selector-exists('.foo li') // false
selector-exists('.bar') // false

.foo
  color red

  a
    font-size 12px

selector-exists('.foo') // true
selector-exists('.foo a') // true
selector-exists('.foo li') // false
selector-exists('.bar') // false

此方法不考虑当前上下文含义：

¥This method does not take into account the current context meaning:

.foo
  color red

  a
    font-size 12px

  selector-exists('a') // false
  selector-exists(selector() + ' a') // true

.foo
  color red

  a
    font-size 12px

  selector-exists('a') // false
  selector-exists(selector() + ' a') // true

opposite-position(positions)

返回给定 positions 的相反数。

¥Return the opposite of the given positions.

opposite-position(right)
// => left

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

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

opposite-position(right)
// => left

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

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

image-size(path)

返回在 path 处找到的图片的 width 和 height。查找的执行方式与 @import 相同，但由 paths 设置更改。

¥Returns the width and height of the image found at path. Lookups are performed in the same manner as @import, altered by the paths setting.

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

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

embedurl(path[, encoding])

以 url() 字面量形式返回内嵌图片，并使用 encoding 进行编码。

¥Returns an inline image as a url() literal, encoded with encoding.

（可用编码：base64（默认）和 utf8）。

¥(Available encodings: base64 (default), and utf8).

background: embedurl('logo.png')
// => background: url("data:image/png;base64,…")

background: embedurl('logo.svg', 'utf8')
// => background: url("data:image/svg+xml;charset=utf-8,…")

background: embedurl('logo.png')
// => background: url("data:image/png;base64,…")

background: embedurl('logo.svg', 'utf8')
// => background: url("data:image/svg+xml;charset=utf-8,…")

添加属性（名称，表达式）

¥add-property(name, expr)

添加属性 name，并将给定的 expr 添加到最近的块。

¥Adds property name, with the given expr to the closest block.

例如：

¥For example:

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

body
  foo: something()

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

body
  foo: something()

产量：

¥yields:

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

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

接下来，"magic" current-property 局部变量开始发挥作用。该变量自动可供函数体使用，并包含具有当前属性名称和值的表达式。

¥Next, the "magic" current-property local variable comes into play. This variable is automatically available to function bodies, and contains an expression with the current property's name, and value.

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

¥For example, if we were to inspect this local variable using p(), we get the following:

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

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

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

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

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

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

使用 current-property，我们可以进一步扩展示例，并使用新值和条件复制属性，以确保该函数仅在属性值中使用。

¥Using current-property we can take our example a bit further, and duplicate the property with new values, and a conditional to ensure the function is only used within a property value.

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;
}

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;
}

产量：

¥yields:

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

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

如果你在上面的示例中注意到，bar 仅在初始调用中出现，因为我们返回了 something(15px)，所以它在表达式中保留在适当的位置，但是其他表达式不会考虑表达式的其余部分。

¥If you noticed in the example above, bar is only present for the initial call, since we returned something(15px), it remained in-place within the expression, however the others do not take the rest of the expression into account.

下面我们更强大的解决方案定义了一个名为 replace() 的函数，该函数克隆表达式以防止突变，将表达式的字符串值替换为另一个表达式，然后返回克隆的表达式。然后我们继续替换表达式中的 __CALL__，它表示对 something() 的循环调用。

¥Our more robust solution below defines a function named replace() which clones the expression to prevent mutation, replaces the string value of an expression with another, and returns the cloned expression. We then move on to replace __CALL__ within the expressions, which represents the cyclic call to 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() must be used within a property')

body
  foo: something(5px) bar baz

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() must be used within a property')

body
  foo: something(5px) bar baz

产量：

¥yields:

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

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

现在，我们的实现在调用它的属性和调用的位置方面都是完全透明的。

¥Our implementation is now fully transparent both in regards to the property it is called within, and the position of the call.

这个强大的概念有助于浏览器对函数调用（例如渐变）的透明支持。

¥This powerful concept aids in transparent vendor support for function calls, such as gradients.

控制台函数

¥Console Functions

warn(msg)

警告给定错误 msg。不退出。

¥Warn with the given error msg. Does not exit.

warn("oh noes!")

warn("oh noes!")

error(msg)

退出 Stylus，并显示给定错误 msg。

¥Exit Stylus with the given error msg.

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

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

p(expr)

检查给定的 expr：

¥Inspect the given 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)

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)

标准输出：

¥stdout:

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)

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)

外部文件函数

¥External File Functions

json(path[, options])

将 path 处的 JSON 文件转换为 Stylus 变量或对象。嵌套变量对象键用破折号 (-) 连接。

¥Convert the JSON file at path into Stylus variables or an object. Nested variable object keys are joined with a dash (-).

例如，以下示例 media-queries.json 文件：

¥For example, the following sample media-queries.json file:

{
    "small": "screen and (max-width:400px)",
    "tablet": {
        "landscape": "screen and (min-width:600px) and (orientation:landscape)",
        "portrait": "screen and (min-width:600px) and (orientation:portrait)"
    }
}

{
    "small": "screen and (max-width:400px)",
    "tablet": {
        "landscape": "screen and (min-width:600px) and (orientation:landscape)",
        "portrait": "screen and (min-width:600px) and (orientation:portrait)"
    }
}

可以通过以下方式使用：

¥May be used in the following ways:

json('media-queries.json')

@media small
// => @media screen and (max-width:400px)

@media tablet-landscape
// => @media screen and (min-width:600px) and (orientation:landscape)

vars = json('vars.json', { hash: true })
body
  width: vars.width

vars = json('vars.json', { hash: true, leave-strings: true })
typeof(vars.icon)
// => 'string'

// don't throw an error if the JSON file doesn't exist
optional = json('optional.json', { hash: true, optional: true })
typeof(optional)
// => 'null'

json('media-queries.json')

@media small
// => @media screen and (max-width:400px)

@media tablet-landscape
// => @media screen and (min-width:600px) and (orientation:landscape)

vars = json('vars.json', { hash: true })
body
  width: vars.width

vars = json('vars.json', { hash: true, leave-strings: true })
typeof(vars.icon)
// => 'string'

// don't throw an error if the JSON file doesn't exist
optional = json('optional.json', { hash: true, optional: true })
typeof(optional)
// => 'null'

use(path)

你可以在 .styl 文件中使用给定 path 和 use() 函数的任何 JS 插件，如下所示：

¥You can use any JS-plugin at given path with use() function right inside your .styl files, like this:

use("plugins/add.js")

width add(10, 100)
// => width: 110

use("plugins/add.js")

width add(10, 100)
// => width: 110

本例中的 add.js 插件如下所示：

¥And the add.js plugin in this case looks this way:

var plugin = function(){
  return function(style){
    style.define('add', function(a, b) {
      return a.operate('+', b);
    });
  };
};
module.exports = plugin;

var plugin = function(){
  return function(style){
    style.define('add', function(a, b) {
      return a.operate('+', b);
    });
  };
};
module.exports = plugin;

如果你想返回任何 Stylus 对象，例如 RGBA、Ident 或 Unit，你可以使用提供的 Stylus 节点，如下所示：

¥If you'd like to return any Stylus objects like RGBA, Ident, or Unit, you could use the provided Stylus nodes like this:

var plugin = function(){
  return function(style){
    var nodes = this.nodes;
    style.define('something', function() {
      return new nodes.Ident('foobar');
    });
  };
};
module.exports = plugin;

var plugin = function(){
  return function(style){
    var nodes = this.nodes;
    style.define('something', function() {
      return new nodes.Ident('foobar');
    });
  };
};
module.exports = plugin;

你可以使用 哈希对象 将任何选项作为可选的第二个参数传递：

¥You can pass any options as an optional second argument, using a hash object:

use("plugins/add.js", { foo: bar })

use("plugins/add.js", { foo: bar })

未定义的函数

¥Undefined Functions

未定义的函数作为字面量输出。因此，例如，我们可以在 CSS 中调用 rgba-stop(50%, #fff)，它会按照你的预期输出。我们也可以在助手中使用它。

¥Undefined functions are output as literals. So, for example, we may call rgba-stop(50%, #fff) within our css, and it will output as you would expect. We can use this within helpers as well.

在下面的示例中，我们简单地定义了函数 stop()，它返回字面量 rgba-stop() 调用。

¥In the example below we simply define the function stop() which returns the literal rgba-stop() call.

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

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

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

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