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 库和设计系统倾向于共享和覆盖表示为嵌套映射（包含映射的映射）的配置。

¥Sass libraries and design systems tend to share and override configurations that are represented as nested maps (maps that contain maps that contain maps).

为了帮助你使用嵌套映射，某些映射函数支持深度操作。例如，如果你将多个键传递给 map.get()，它将按照这些键来查找所需的嵌套映射：

¥To help you work with nested maps, some map functions support deep operations. For example, if you pass multiple keys to map.get(), it will follow those keys to find the desired nested map:

  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() 相同，但嵌套映射值也会递归合并。

¥Identical to map.merge(), except that nested map values are also recursively merged.

  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 为空，则返回 $map 的副本，不包含与 $key 关联的值。

¥If $keys is empty, returns a copy of $map without a value associated with $key.

  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 中最后一个键的键集合从左到右查找要更新的嵌套映射。

¥If $keys is not empty, follows the set of keys including $key and excluding the last key in $keys, from left to right, to find the nested map targeted for updating.

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

¥Returns a copy of $map where the targeted map does not have a value associated with the last key in $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 关联的值。

¥If $keys is empty, returns the value in $map associated with $key.

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

¥If $map doesn’t have a value associated with $key, returns 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: ✗

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

如果 $keys 不为空，则按照包含 $key 且排除 $keys 中最后一个键的键集合从左到右查找要搜索的嵌套映射。

¥If $keys is not empty, follows the set of keys including $key and excluding the last key in $keys, from left to right, to find the nested map targeted for searching.

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

¥Returns the value in the targeted map associated with the last key in $keys.

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

¥Returns null if the map does not have a value associated with the key, 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.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 关联的值。

¥If $keys is empty, returns whether $map contains a value associated with $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: ✗

Only Dart Sass supports calling `map.has-key()` with more than two
arguments.

如果 $keys 不为空，则按照包含 $key 且排除 $keys 中最后一个键的键集合从左到右查找要搜索的嵌套映射。

¥If $keys is not empty, follows the set of keys including $key and excluding the last key in $keys, from left to right, to find the nested map targeted for searching.

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

¥Returns true if the targeted map contains a value associated with the last key in $keys.

如果没有，或者映射中缺少 $keys 中的任何键或引用的值不是映射，则返回 false。

¥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

返回 $map 中所有键的逗号分隔列表。

¥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.

如果未传递 $keys，则返回一个新映射，其中包含 $map1 和 $map2 中的所有键和值。

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

如果 $map1 和 $map2 具有相同的键，则 $map2 的值优先。

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

返回的映射中也出现在 $map1 中的所有键的顺序与 $map1 中的顺序相同。$map2 的新键出现在映射的末尾。

¥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.

如果 $keys 不为空，则按照 $keys 查找要合并的嵌套映射。如果映射中缺少 $keys 中的任何键或引用的值不是映射，则将该键处的值设置为空映射。

¥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.

返回 $map1 的副本，其中目标映射被替换为新映射，其中包含目标映射和 $map2 中的所有键和值。

¥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

返回 $map 的副本，不带任何与 $keys 关联的值。

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

如果 $keys 中的键在 $map 中没有关联值，则会被忽略。

¥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.

如果未传递 $keys，则返回 $map 的副本，其中 $key 处的值设置为 $value。

¥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.

如果通过了 $keys，则按照 $keys 查找要更新的嵌套映射。如果映射中缺少 $keys 中的任何键或引用的值不是映射，则将该键处的值设置为空映射。

¥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.

返回 $map 的副本，其中 $key 处的目标映射值设置为 $value。

¥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

返回 $map 中所有值的逗号分隔列表。

¥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