Sass 之内置模块

hghh
439 阅读7分钟

sass 提供了以下内置模块：

  • color：颜色操作方法
  • list：列表操作方法
  • map：对象操作方法
  • math：数学操作方法
  • meta：内部操作方法
  • selector：选择器操作方法
  • string：字符串操作方法

sass:color

  1. color.adjust() 或 adjust-color()：修改颜色配置（在原来的颜色上加上参数的颜色配置得到最终颜色）

    (1). 参数：$color, $red: null, $green: null, $blue: null, $hue: null, $saturation: null, $lightness: null, $whiteness: null, $blackness: null, $alpha: null

    (2). 参数要求：

    • $red, $green, $blue：[-255, 255] 之间无单位数字
    • $hue：带单位（deg）或无单位数字
    • $saturation, $lightness, $whiteness, $blackness：[-100%, 100%]之间带单位（%）或无单位数字
    • $alpha：[-1, 1]之间无单位数字

    (3). 设置模式

    • RGB：$red, $green, $blue
    • HSL：$hue, $saturation, $lightness
    • HWB：$hue, $whiteness, $blackness

只能通过RGB、HSL、HWB三种方式其中一种设置颜色，传递两种方式的参数将会报错

注意与以下两种改变颜色配置方法的区别：

  • color.change()：原来的颜色替换参数的颜色设置得到最终的颜色
  • color.scale()：$red、$green、$blue用0和255计算差值，$saturation、$lightness、$alpha用0% 和 100% 计算差值，如以下例子：将R值转变为100，在RGB中，R的值为0~255，原来颜色的R值为61，首先获取原颜色的R值和255之间差值，取得差值的20%，然后加上原来颜色的R值61,也就是 (255 - 61) * 20% + 61= 100。如果$red为-20%，那将取的是原来颜色的R值与0之间的差值，用原来颜色R值减去差值的20%，也就是61 - (61 - 0) * 20% = 49，最后四舍五入 
    $colorMain: rgba(#3d48de, 0.3);  // R 值为61
$funcData: change-color, adjust-color, scale-color, ie-hex-str;
@mixin func($funcName) {
  @if $funcName == change-color {
    background-color: change-color($colorMain, $red: 123);
  }@else if $funcName == adjust-color {
    background-color: adjust-color($colorMain, $red: 123);
  }@else if $funcName == scale-color {
    background-color: scale-color($colorMain, $red: 20%);
  }@else if $funcName == ie-hex-str {
    background-color: ie-hex-str($colorMain);
  }
}
@each $value in $funcData {
  .div-#{$value} {
    @include func($value);
  }
}

// 编译后的 css
.div-change-color {
  background-color: rgba(123, 72, 222, 0.3);
}
.div-adjust-color {
  background-color: rgba(184, 72, 222, 0.3);
}
.div-scale-color {
  background-color: rgba(100, 72, 222, 0.3);
}
.div-ie-hex-str {
  background-color: #4D3D48DE;
}

  1. color.hwb($hue, $whiteness, $blackness, $alpha:1)：返回给定配置的颜色

    • $hue：[0deg, 360deg] 有单位（%）或无单位数字
    • $whiteness、$blackness：[0%， 100%] 带单位（%）数字
    • $alpha：[0, 1] 或 [0%, 100%]

  2. adjust-hue($color, $degrees)：修改颜色 hue 配置

    $degrees：[-360, 360] 之间的带单位（deg）或无单位数字

  3. color.alpha($color)、alpha($color)、opacity($color)：返回颜色的透明度

    • color.red()：返回颜色的红色值
    • color.green()：返回颜色的绿色值
    • color.blue()：返回颜色的蓝色值
    • color.hue()：返回颜色的色调
    • color.saturation()：返回颜色的色彩饱和度
    • color.lightness()：返回颜色的亮度
    • color.blackness()：返回颜色的黑度
    • color.whiteness()：返回颜色的白度
    • color.alpha()：返回颜色的暗度

  4. color.complement($color) 或 complement($color)：返回颜色的互补色，相当于 color.adjust($color, $hue: 180deg)

  5. color.grayscale($color) 或 grayscale($color)：返回与该颜色亮度一致的灰色，相当于 color.change($color, $saturation: 0%)

  6. darken($color, $amount)：减少颜色的亮度（减少颜色 HSL 配置中的亮度 $amount）， $amount 必须为 [0,100] 之间的无单位数字或带单位数字（%）

  7. lighten($color, $amount)：增加颜色的亮度 $amount（ [ 0%, 100% ] ）

  8. opacify($color, $amount) 或 fade-in($color, $amount)：增加颜色的透明度 $amount ( [ 0, 1 ] )

  9. transparentize($color, $amount) 或 fade-out($color, $amount)：减少颜色的透明度 $amount ( [ 0, 1 ] )

  10. saturate($color, $amount)：增加颜色的饱和度 $amount（ [ 0%, 100% ] ）

  11. desaturate($color, $amount)：减少颜色的饱和度（减少颜色 HSL 配置中的饱和度 $amount），$amount 必须为 [0,100] 之间的无单位数字或带单位数字（%）

  12. color.ie-hex-str($color) 或 ie-hex-str($color)：返回适用 IE 浏览器的颜色算法的颜色

  13. color.invert($color, $weight: 100%) 或 invert($color, $weight: 100%)：返回与给定 $color 倒数 $weight 比重的颜色，$weight 必须为 [0%, 100%] 之间的数字。$weight 为 50% 时，返回的颜色为 #808080

  14. color.mix($color1, $color2, $weight: 50%) 或 mix($color1, $color2, $weight: 50%)：返回两个颜色的混合颜色，$weight （ [ 0%, 100% ] ）代表 $color1 的颜色比重

sass:list

在 sass 中， map 对象是特殊的 list 数组，所以以下这些方法在 map 对象中同样可以适用。同样，单个值也被当为数组，所以这些方法也适用。

  1. list.append() 或 append()

    参数：($list, $val, $separator:auto) 。$separator，分割数组方式，可选值：auto(按 $list 原方式分割数组)，comma(按逗号分割数组)，space(按空格分割数组)，slash(按斜线分割数组)

    返回：$val 添加到 $list 后的副本

  2. list.join() 或 join()

    参数：$list1, $list2,$separator: auto, $bracketed: auto。$separator 可选值：auto(按 $list1 原方式分割数组，$list1 没有的话按照 $list2 原方式分割数组，$list2 没有的话按照 comma 分割数组)，comma(按逗号分割数组)，space(按空格分割数组)，slash(按斜线分割数组) ；$bracketed：新数组是否由中括号包裹，可选值：auto(是否有中括号与 $list1 保持一致)，真值 truthy，假值 falsey。

    返回：$list1 和 $list2 合并后的数组

  3. list.index($list, $value) 或 index($list, $value)

    返回 $value 在 $list 中的位置（从 1 开始），找不到返回 null，重复出现返回第一次的位置

  4. list.is-bracketed($list) 或 is-bracketed($list)

    返回 $list 是否由中括号包裹

  5. list.length($list) 或 length($list)

    返回数组长度，在 map 中返回键值对数目

  6. list.separator($list) 或 separator($list)

    返回 $list 的分割方式，可能值为 space, comma, slash

  7. list.nth($list, $n) 或 nth($list, $n)

    返回 $list 的 第 $n (第一个为 1)个元素，$n 超过数组长度报错，$n 可为负数，代表从数组末尾开始算起

  8. list.set-nth($list, $n, $value) 或 set-nth($list, $n, $value)

    返回 $list 第 $n （第一个为1）值修改为 $value 的副本（不修改原数组），$n 超过数组长度报错，$n 可为负数，代表从数组末尾开始算起

  9. list.zip($list...) 或 zip($list...)

    返回第一个数组的元素与后边每个数组相应位置的元素联合的子数组（子数组用空格分割，父数组用逗号分割）。子数组的个数与所有数组中长度最短的保持一致

    @debug list.zip(10px 50px 100px, short mid long); // 10px short, 50px mid, 100px long
@debug list.zip(10px 50px 100px, short mid); // 10px short, 50px mid
@debug list.zip(10px 50px, short mid long); // 10px short, 50px mid

sass:map

  1. map.get($map, $key, $keys...) 或 map-get($map, $key, $keys...)

    如果 $keys 为空，返回 $map 中 $key 的值；如果 $keys 不为空，返回 $map 中从左到右查找属性的值。找不到返回 null

  2. map.set($map, $key, $value) 或 map.set($map, $keys..., $key, $value)

    返回设置 $map 上 $key 值的副本。传递 $keys 时，在 $map 中查找属性的值，找不到的话新增该属性并设置值。

  3. map.has-key($map, $key, $keys...) 或 map-has-key($map, $key, $keys...)

    如果 $keys 为空，返回 $map 是否有 $key ；如果 $keys 不为空，返回 $map 中从左到右是否有该属性。找不到属性返回 false

  4. map.keys($map) 或 map-keys($map)

    返回 $map 属性组成的数组，该数组用逗号分割。只返回对象的一级属性，不会返回二级嵌套属性

  5. map.values($map) 或 map-values($map)

    返回 $map 属性值组成的数组，该数组用逗号分割。一级属性直接返回值，二级嵌套属性返回对应属性的对象

  6. map.merge($map1, $keys..., $map2) 或 map-merge($map1, $keys..., $map2)

    $keys 为空时，返回 $map1 和 $map2 所有属性合并的对象 $map1 和 $map2 属性相同时，取 $map2 对应属性的值；$keys 不为空时，将 $map2 中的所有属性挂载到 $map1 按照 $keys 查找的属性上，如果挂载时属性重复，取 $map2 中的值，如果 $map1 找不到属性则创建新属性。

    $fonts: (
  "Helvetica": (
    "weights": (
      "lightest": 100,
      "light": 300
    )
  )
);
$heavy-weights: ("medium": 500, "bold": 700);

@debug map.merge($fonts, "Helvetica", "weights", $heavy-weights);
// (
//   "Helvetica": (
//     "weights": (
//       "lightest": 100,
//       "light": 300,
//       "medium": 500,
//       "bold": 700
//     )
//   )
// )

  7. map.deep-merge($map1, $map2)

    返回深度合并两个对象后的对象，与 map.merge() 基本一致，除了嵌套的映射值也会被递归合并

    $helvetica-light: (
  "weights": (
    "lightest": 100,
    "light": 300
  )
);
$helvetica-heavy: (
  "weights": (
    "medium": 500,
    "bold": 700
  )
);

@debug map.deep-merge($helvetica-light, $helvetica-heavy);
// (
//   "weights": (
//     "lightest": 100,
//     "light": 300,
//     "medium": 500,
//     "bold": 700
//   )
// )
@debug map.merge($helvetica-light, $helvetica-heavy);
// (
//   "weights": (
//     "medium: 500,
//     "bold": 700
//   )
// )

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

    返回删除 $keys 属性的 $map 对象副本（注意 $keys 传参与 map.deep-remove() 的区别）

    $font-weights: ("regular": 400, "medium": 500, "bold": 700);

@debug map.remove($font-weights, "regular"); // ("medium": 500, "bold": 700)
@debug map.remove($font-weights, "regular", "bold"); // ("medium": 500)
@debug map.remove($font-weights, "bolder"); // ("regular": 400, "medium": 500, "bold": 700)

  9. map.deep-remove($map, $key, $keys...)

    返回删除 $map 上某个属性的对象（**注意 keys 传参与 map.remove() 的区别**）。如果 \keys 为空，返回删除 $map 上 $key 属性的对象；如果 $keys 不为空，从左到右寻找 $map 上对应的属性，返回删除该属性的对象，找不到的话返回与原对象一样的对象。

    $font-weights: ("regular": 400, "medium": 500, "bold": 700);
@debug map.deep-remove($font-weights, "regular"); // ("medium": 500, "bold": 700)

$fonts: (
  "Helvetica": (
    "weights": (
      "regular": 400,
      "medium": 500
    )
  )
);
@debug map.deep-remove($fonts, "Helvetica", "weights", "regular");
// (
//   "Helvetica": (
//     "weights: (
//       "medium": 500
//     )
//   )
// )

sass:math

  1. 值

    • math.$e：返回自然对数 e

    • math.$pi：返回圆周率 π

  2. 边界操作

    • math.ceil($number) 或 ceil($number)：返回 $number 向上取整
    • math.floor($number) 或 floor($number)：返回 $number 向下取整
    • math.round($number) 或 math.round($number)：返回 $number 的四舍五入
    • math.clamp($min, $number, $max)：判断 $number 是否在 $min 和 $max 之间，是的话返回 $number，否则小于 $min 返回 $min，大于 $max 的话返回 $max。三个参数的单位必须兼容，或者都为无单位数字
    • math.max($number...) 或 max($number...)：返回参数中的最大值
    • math.min($number...) 或 min($number...)：返回参数中的最小值

  3. 距离

    • math.abs($number) 或 abs($number)：返回 $number 的绝对值
    • math.hypot($number...)：返回 $number 每个数字平方和的平方根，如 math.hypot(3, 4); // 5：3² + 4² 平方根

  4. 指数操作

    • math.log($number, $base: null)：返回 $number 基于 $base 的对数， $base 没有传递的话取自然对数 e
    • math.pow($base, $exponent)：返回 $bae 的 $exponent 次方
    • math.sqrt($number)：返回 $number 的平方根

  5. 三角函数操作

    • math.cos($number)：返回 $number 的余弦值，$number 必须单位必须与 deg 兼容的单位或者无单位（当做 rad 单位，弧度）
    • math.sin($number)：返回 $number 的正弦值，$number 必须单位必须与 deg 兼容的单位或者无单位（当做 rad 单位，弧度）
    • math.tan($number)：返回 $number 的正切值，$number 必须单位必须与 deg 兼容的单位或者无单位（当做 rad 单位，弧度）
    • math.acos($number)：返回 $number 的反余弦值（单位 deg），$number 必须为无单位数字
    • math.asin($number)：返回 $number 的反正弦值（单位 deg），$number 必须为无单位数字
    • math.atan($number)：返回 $number 的反正切值（单位 deg），$number 必须为无单位数字
    • math.atan2($x, $y)：返回二维坐标系中任意一个点（$x, $y）和原点（0, 0）的连线与y轴正半轴的夹角大小

  6. 单位函数操作

    • math.compatible($number1, $number2) 或 comparable($number1, $number2)：返回 $number1， $number2 两个数字的单位是否兼容。假如返回 true ，两个数字可以相加、相减、比较，否则将会报错
    • math.is-unitless($number) 或 unitless($number)：返回 $number 是否无单位
    • math.unit($number) 或 unit($number)：返回 $number 的单位，无单位返回空字符串

  7. 其他

    • math.div($number1, $number2)：返回 $number1 和 $number2 两个数字相除后的结果
    • math.percentage($number) 或 percentage($number)：返回 $number 转换为百分比的值，相当于 $number * 100%，$number 必须为无单位数字
    • math.random($limit: null) 或 random($limit: null)：$limit 必须为大于等于1的整数。当 $limit 不传时，返回 (0,1) 之间的小数；当 $limit 为1时，返回1；当 $limit 大于1时，返回 (1, $limit] 之间的整数

sass:meta

  1. meta.load-css($url, $with: null)：加载 $url 文件，$with 提供模块加载配置（变量名不带 $），配置模块中变量的值。

    // dark-theme/_code.scss
$border-contrast: false !default;
code {
  background-color: #6b717f;
  color: #d2e1dd;
  @if $border-contrast {
    border-color: #dadbdf;
  }
}

// style.scss
@use "sass:meta";
body.dark {
  @include meta.load-css("dark-theme/code",
      $with: ("border-contrast": true));
}

    与 @use 相同的地方：

    • 只会加载一次
    • 不能为已经加载的模块提供配置

    与 @use 不同的地方：

    • 不能在当前模块中使用加载模块中的任何成员
    • 可以在任何地方使用
    • $url 可以来自变量或插值

  2. meta.calc-args($calc)：返回传入 $calc 计算的参数

    @debug meta.calc-args(calc(100px + 10%)); // 100px + 10%
@debug meta.calc-args(clamp(50px, var(--width), 1000px)); // 50px, var(--width), 1000px

  3. meta.calc-name($calc)：返回传入 $calc 计算的名称

    @debug meta.calc-name(calc(100px + 10%)); // "calc"
@debug meta.calc-name(clamp(50px, var(--width), 1000px)); // "clamp"

  4. meta.call($function, $args...) 或 call($function, $args...)：将 $args 传给 $function 并返回执行的结果。 $function 必须为 meta.get-function() 返回的函数

    @use "sass:list";
@use "sass:meta";
@use "sass:string";

/// Return a copy of $list with all elements for which $condition returns `true`
/// removed.
@function remove-where($list, $condition) {
  $new-list: ();
  $separator: list.separator($list);
  @each $element in $list {
    @if not meta.call($condition, $element) {
      $new-list: list.append($new-list, $element, $separator: $separator);
    }
  }
  @return $new-list;
}

$fonts: Tahoma, Geneva, "Helvetica Neue", Helvetica, Arial, sans-serif;

content {
  @function contains-helvetica($string) {
    @return string.index($string, "Helvetica");
  }
  font-family: remove-where($fonts, meta.get-function("contains-helvetica"));
}

  5. meta.content-exists() 或 content-exists()：返回在当前 mixin 是否有传递 @content。该函数只能用在 mixin 中，在其他地方会报错。

    @mixin debug-content-exists {
@debug meta.content-exists();
@content;
}

@include debug-content-exists; // false
@include debug-content-exists { // true

}

  6. meta.feature-exists($feature) 或 feature-exists($feature)：返回当前 Sass 是否支持 $feature。

    目前支持的 $feature：

    • global-variable-shadowing
    • extend-selector-pseudoclass
    • units-level3
    • at-error
    • custom-property

  7. meta.function-exists($name, $module: null) 或 function-exists($name, $module:null)：返回 $name 函数是否有定义，$module 要与当前文件使用的 @use 规则命名空间一致。

  8. meta.get-function($name, $css: false, $module: null) 或 get-function($name, $css: false, $module: null)：返回名称为 $name 的 function。默认情况下，没有 $name 的函数时，会报错，但是 $css 为 true 时，会返回普通的 css 函数。$css 和 $module 两个参数只能传递一个，不能同时传递，传 $module 时，注意要使用参数名传参。

  9. meta.global-variable-exists($name, $module: null) 或 global-variable-exists($name, $module: null)：返回是否存在名称为 $name （传参时不用写 $）的全局变量。

  10. meta.variable-exists($name) 或 variable-exists($name)：返回当前作用域下是否存在名称为 $name （传参时不用写 $）的变量。

  11. meta.mixin-exists($name, $module: null) 或 mixin-exists($name, $module: null)：返回是否存在名称为 $name 的mixin。

  12. meta.inspect($value) 或 inspect($value)：返回 $value 的字符串。

  13. meta.keywords($args) 或 keywords($args)：返回调用 mixin 或 function 中传递的参数 $args，返回的是一个对象，为参数的名称和值。没有通过名称传参的话返回的是一个空对象。

    @use "sass:meta";

@mixin syntax-colors($args...) {
  @debug meta.keywords($args);
  // (string: #080, comment: #800, variable: #60b)

  @each $name, $color in meta.keywords($args) {
    pre span.stx-#{$name} {
      color: $color;
    }
  }
}

@include syntax-colors(
  $string: #080,
  $comment: #800,
  $variable: #60b,
)

  14. meta.module-functions($module)：以 map 形式返回 $module 定义的所有函数。

  15. meta.module-variables($module)：以 map 形式返回 $module 定义的所有变量。

  16. meta.type-of($value) 或 type-of($value)：返回 $value 的类型

    可返回的值为：

    • number
    • string
    • color
    • map
    • calculation
    • bool
    • null
    • function
    • arglist

sass:selector

  1. selector.is-superselector($super, $sub) 或 is-superselector($super, $sub)：返回 $super 选择器匹配的元素是否包含 $sub 选择器匹配的元素

    @debug selector.is-superselector("a", "a.disabled"); // true
@debug selector.is-superselector("a.disabled", "a"); // false
@debug selector.is-superselector("a", "sidebar a"); // true
@debug selector.is-superselector("sidebar a", "a"); // false
@debug selector.is-superselector("a", "a"); // true

  2. selector.append($selectors...) 或 selector-append($selectors...)：返回将 $selectors 中的每个选择器联合起来的选择器。$selectors 中的每一项可以包含占位选择器，但是不能包含父选择器。如果 $selectors 的某一项是数组，则每个数组成员分别进行联合。注意联合方式是没有空格的，也就是联合之后的选择器匹配的元素是满足联合前每个选择器的元素。

    @debug selector.append("a", ".disabled"); // a.disabled
@debug selector.append(".accordion", "__copy"); // .accordion__copy
@debug selector.append(".accordion", "__copy, __image"); // .accordion__copy, .accordion__image

  3. selector.nest($selectors...) 或 selector-nest($selectors...)：返回将 $selectors 中的每个选择器嵌套起来的选择器。$selectors 中的每一项可以包含占位选择器，除了第一项外也可以包含父选择器。如果 $selectors 的某一项是数组，则每个数组成员分别进行嵌套。注意嵌套方式是有空格的，也就是嵌套之后的选择器，匹配的元素是 $selectors 每一项嵌套父子关系的元素。

  4. selector.extend($selector, $extendee, $extender) 或 selector-extend($selector, $extendee, $extender)：返回 $selector 选择器，以及 $selector 选择器中 $extendee 使用 @extend $extendee 扩展后的选择器

    #{$extender} {
  @extend #{$extendee};
}

@debug selector.extend("a.disabled", "a", ".link"); // a.disabled, .link.disabled
@debug selector.extend("a.disabled", "h1", "h2"); // a.disabled
@debug selector.extend(".guide .info", ".info", ".content nav.sidebar");
// .guide .info, .guide .content nav.sidebar, .content .guide nav.sidebar

  5. selector.replace($selector, $original, $replacement) 或 selector-replace($selector, $original, $replacement)：返回 $selector 中 $original 替换为 $replacement 后的选择器

    @debug selector.replace("a.disabled", "a", ".link"); // .link.disabled
@debug selector.replace("a.disabled", "h1", "h2"); // a.disabled
@debug selector.replace(".guide .info", ".info", ".content nav.sidebar");
// .guide .content nav.sidebar, .content .guide nav.sidebar

  6. selector.unify($selector1, $selector2) 或 selector-unify($selector1, $selector2)：返回同时匹配 $selector1 和 $selector2 选择器的元素，没有匹配返回 null

    @debug selector.unify("a", ".disabled"); // a.disabled
@debug selector.unify("a.disabled", "a.outgoing"); // a.disabled.outgoing
@debug selector.unify("a", "h1"); // null
@debug selector.unify(".warning a", "main a"); // .warning main a, main .warning a

  7. selector.parse($selector) 或 selector-parse($selector)：将 $selector 选择器以选择器值的形式返回。

  8. selector.simple-selectors($selector) 或 simple-selectors($selector)：返回 $selector 拆分为一个一个字符串的列表。这意味着 $selector 不允许包含逗号或空格。

    @debug selector.simple-selectors("a.disabled"); // a, .disabled
@debug selector.simple-selectors("main.blog:after"); // main, .blog, :after

sass:string

  1. string.quote($string) 或 quote($string)：返回 $string 的带引号格式

  2. string.unquote($string) 或 unquote($string)：返回 $string 的不带引号格式

  3. string.index($string, $substring) 或 str-index($string, $substring)：返回 $substring 在 $string 中的位置，没有找到返回 null

  4. string.index($string, $insert, $index) 或 str-insert($string, $insert, $index)：返回在 $string 中 $index 位置插入 $insert 后的字符串。$index 比 $string 长度大的话插入到最后位置，$index 负数绝对值比 $string 长度大的话插入到其实位置

    @debug string.insert("Roboto Bold", " Mono", 7); // "Roboto Mono Bold"
@debug string.insert("Roboto Bold", " Mono", -6); // "Roboto Mono Bold"

@debug string.insert("Roboto", " Bold", 100); // "Roboto Bold"
@debug string.insert("Bold", "Roboto ", -100); // "Roboto Bold"

  5. string.length($string) 或 str-length($string)：返回 $string 的长度

  6. string.slice($string, $start-ar, $end-at: -1) 或 str-slice($string, $start-at, $end-at: -1)：返回 $string 从 $start-at 截取到 $end-at 的子字符串（起始跟末尾都包含）

  7. string.to-upper-case($string) 或 to-upper-case($string)：返回 $string 转换为大写格式的字符串

  8. string.to-lower-case($string) 或 to-lower-case($string)：返回 $string 转换为小写的字符串

  9. string.unique-id() 或 unique-id()：返回一个随机生成的不带引号的字符串，它保证是一个有效的 CSS 标识符并且在当前 Sass 编译中是唯一的。

avatar
文章
阅读
粉丝