sass:map

Dart Sass: since 1.23.0
LibSass: ✗
Ruby Sass: ✗

Only Dart Sass currently supports loading built-in modules with @use. Users of other implementations must call functions using their global names instead.

💡 Fun fact:

Sass 库和设计系统倾向于共享和覆盖以嵌套映射（包含映射的映射）表示的配置。

为了帮助你处理嵌套映射，一些映射函数支持深度操作。例如，如果向 map.get() 传递多个键，它将跟随这些键找到所需的嵌套映射：

SCSS

Sass

    Playground
  SCSS Syntax@use "sass:map";

$config: (a: (b: (c: d)));
@debug map.get($config, a, b, c); // d

    Playground
  Sass Syntax@use "sass:map"

$config: (a: (b: (c: d)))
@debug map.get($config, a, b, c) // d

map.deep-merge($map1, $map2) //=> map

Dart Sass: since 1.27.0
LibSass: ✗
Ruby Sass: ✗

与 map.merge() 相同，不同之处在于嵌套的映射值也会递归合并。

  SCSS

  Sass

      
      Playground
    SCSS Syntax@use "sass:map";

$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
//   )
// )

      
      Playground
    Sass Syntax@use "sass:map"

$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
//   )
// )

map.deep-remove($map, $key, $keys...) //=> map

Dart Sass: since 1.27.0
LibSass: ✗
Ruby Sass: ✗

如果 $keys 为空，返回不包含与 $key 关联的值的 $map 的副本。

  SCSS

  Sass

      Playground
    SCSS Syntax@use "sass:map";

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

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

      Playground
    Sass Syntax@use "sass:map"

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

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

如果 $keys 非空，从左到右跟随包括 $key 在内且不包括 $keys 中最后一个键的键集，找到要更新的嵌套映射。

返回 $map 的副本，其中目标映射没有与 $keys 中最后一个键关联的值。

  SCSS

  Sass

      
      Playground
    SCSS Syntax@use "sass:map";

$fonts: (
  "Helvetica": (
    "weights": (
      "regular": 400,
      "medium": 500,
      "bold": 700
    )
  )
);

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

      
      Playground
    Sass Syntax@use "sass:map"

$fonts: ("Helvetica": ("weights": ("regular": 400, "medium": 500, "bold": 700)))

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

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

如果 $keys 为空，返回 $map 中与 $key 关联的值。

如果 $map 没有与 $key 关联的值，返回 null。

  SCSS

  Sass

      
      Playground
    SCSS Syntax@use "sass:map";
$font-weights: ("regular": 400, "medium": 500, "bold": 700);

@debug map.get($font-weights, "medium"); // 500
@debug map.get($font-weights, "extra-bold"); // null

      
      Playground
    Sass Syntax@use "sass:map"
$font-weights: ("regular": 400, "medium": 500, "bold": 700)

@debug map.get($font-weights, "medium")  // 500
@debug map.get($font-weights, "extra-bold")  // null

Dart Sass: since 1.27.0
LibSass: ✗
Ruby Sass: ✗

只有 Dart Sass 支持使用两个以上参数调用 map.get()。

如果 $keys 非空，从左到右跟随包括 $key 在内且不包括 $keys 中最后一个键的键集，找到要搜索的嵌套映射。

返回目标映射中与 $keys 中最后一个键关联的值。

如果映射没有与该键关联的值，或者 $keys 中的任何键在映射中缺失，或引用的不是映射，则返回 null。

  SCSS

  Sass

      
      Playground
    SCSS Syntax@use "sass:map";

$fonts: (
  "Helvetica": (
    "weights": (
      "regular": 400,
      "medium": 500,
      "bold": 700
    )
  )
);

@debug map.get($fonts, "Helvetica", "weights", "regular"); // 400
@debug map.get($fonts, "Helvetica", "colors"); // null

      
      Playground
    Sass Syntax@use "sass:map"

$fonts: ("Helvetica": ("weights": ("regular": 400, "medium": 500, "bold": 700)))

@debug map.get($fonts, "Helvetica", "weights", "regular") // 400
@debug map.get($fonts, "Helvetica", "colors") // null

map.has-key($map, $key, $keys...)
map-has-key($map, $key, $keys...) //=> boolean

如果 $keys 为空，返回 $map 是否包含与 $key 关联的值。

  SCSS

  Sass

      Playground
    SCSS Syntax@use "sass:map";

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

@debug map.has-key($font-weights, "regular"); // true
@debug map.has-key($font-weights, "bolder"); // false

      Playground
    Sass Syntax@use "sass:map"

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

@debug map.has-key($font-weights, "regular") // true
@debug map.has-key($font-weights, "bolder") // false

Dart Sass: since 1.27.0
LibSass: ✗
Ruby Sass: ✗

只有 Dart Sass 支持使用两个以上参数调用 map.has-key()。

如果 $keys 非空，从左到右跟随包括 $key 在内且不包括 $keys 中最后一个键的键集，找到要搜索的嵌套映射。

如果目标映射包含与 $keys 中最后一个键关联的值，则返回 true。

Returns false if it does not, or if any key in $keys is missing from a map or references a value that is not a map.

  SCSS

  Sass

      
      Playground
    SCSS Syntax@use "sass:map";

$fonts: (
  "Helvetica": (
    "weights": (
      "regular": 400,
      "medium": 500,
      "bold": 700
    )
  )
);

@debug map.has-key($fonts, "Helvetica", "weights", "regular"); // true
@debug map.has-key($fonts, "Helvetica", "colors"); // false

      
      Playground
    Sass Syntax@use "sass:map"

$fonts: ("Helvetica": ("weights": ("regular": 400, "medium": 500, "bold": 700)))

@debug map.has-key($fonts, "Helvetica", "weights", "regular") // true
@debug map.has-key($fonts, "Helvetica", "colors") // false

map.keys($map)
map-keys($map) //=> list

Returns a comma-separated list of all the keys in $map.

  SCSS

  Sass

      Playground
    SCSS Syntax@use "sass:map";

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

@debug map.keys($font-weights); // "regular", "medium", "bold"

      Playground
    Sass Syntax@use "sass:map"

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

@debug map.keys($font-weights)  // "regular", "medium", "bold"

map.merge($map1, $map2)
map-merge($map1, $map2)
map.merge($map1, $keys..., $map2)
map-merge($map1, $keys..., $map2) //=> map

⚠️ Heads up!

In practice, the actual arguments to map.merge($map1, $keys..., $map2) are passed as map.merge($map1, $args...). They are described here as $map1, $keys..., $map2 for explanation purposes only.

If no $keys are passed, returns a new map with all the keys and values from both $map1 and $map2.

If both $map1 and $map2 have the same key, $map2’s value takes precedence.

All keys in the returned map that also appear in $map1 have the same order as in $map1. New keys from $map2 appear at the end of the map.

  SCSS

  Sass

      
      Playground
    SCSS Syntax@use "sass:map";

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

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

      
      Playground
    Sass Syntax@use "sass:map"

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

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

Dart Sass: since 1.27.0
LibSass: ✗
Ruby Sass: ✗

Only Dart Sass supports calling map.merge() with more than two arguments.

If $keys is not empty, follows the $keys to find the nested map targeted for merging. If any key in $keys is missing from a map or references a value that is not a map, sets the value at that key to an empty map.

Returns a copy of $map1 where the targeted map is replaced by a new map that contains all the keys and values from both the targeted map and $map2.

  SCSS

  Sass

      
      Playground
    SCSS Syntax@use "sass:map";

$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
//     )
//   )
// )

      
      Playground
    Sass Syntax@use "sass:map"

$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
//     )
//   )
// )

map.remove($map, $keys...)
map-remove($map, $keys...) //=> map

Returns a copy of $map without any values associated with $keys.

If a key in $keys doesn’t have an associated value in $map, it’s ignored.

  SCSS

  Sass

      
      Playground
    SCSS Syntax@use "sass:map";

$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)

      
      Playground
    Sass Syntax@use "sass:map"

$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)

map.set($map, $key, $value)
map.set($map, $keys..., $key, $value) //=> map

⚠️ Heads up!

In practice, the actual arguments to map.set($map, $keys..., $key, $value) are passed as map.set($map, $args...). They are described here as $map, $keys..., $key, $value for explanation purposes only.

If $keys are not passed, returns a copy of $map with the value at $key set to $value.

  SCSS

  Sass

      Playground
    SCSS Syntax@use "sass:map";

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

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

      Playground
    Sass Syntax@use "sass:map"

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

@debug map.set($font-weights, "regular", 300)
// ("regular": 300, "medium": 500, "bold": 700)

Dart Sass: since 1.27.0
LibSass: ✗
Ruby Sass: ✗

Only Dart Sass supports calling map.set() with more than three arguments.

If $keys are passed, follows the $keys to find the nested map targeted for updating. If any key in $keys is missing from a map or references a value that is not a map, sets the value at that key to an empty map.

Returns a copy of $map with the targeted map’s value at $key set to $value.

  SCSS

  Sass

      
      Playground
    SCSS Syntax@use "sass:map";

$fonts: (
  "Helvetica": (
    "weights": (
      "regular": 400,
      "medium": 500,
      "bold": 700
    )
  )
);

@debug map.set($fonts, "Helvetica", "weights", "regular", 300);
// (
//   "Helvetica": (
//     "weights": (
//       "regular": 300,
//       "medium": 500,
//       "bold": 700
//     )
//   )
// )

      
      Playground
    Sass Syntax@use "sass:map"

$fonts: ("Helvetica": ("weights": ("regular": 400, "medium": 500, "bold": 700)))

@debug map.set($fonts, "Helvetica", "weights", "regular", 300)
// (
//   "Helvetica": (
//     "weights": (
//       "regular": 300,
//       "medium": 500,
//       "bold": 700
//     )
//   )
// )

map.values($map)
map-values($map) //=> list

Returns a comma-separated list of all the values in $map.

  SCSS

  Sass

      Playground
    SCSS Syntax@use "sass:map";

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

@debug map.values($font-weights); // 400, 500, 700

      Playground
    Sass Syntax@use "sass:map"

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

@debug map.values($font-weights)  // 400, 500, 700