映射 Map

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

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

💡 有趣的事实：

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

为了帮助您处理嵌套地图，一些地图函数支持深度操作。例如，如果您将多个键传递给 map.get()，它将按照这些键找到所需的嵌套地图：

SCSS Syntax

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

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

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

与 map.merge() 相同，只是嵌套的映射值_also_ 递归合并。

SCSS Syntax

$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

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

如果 $keys 为空，则返回 $map 的副本，但没有与 $key 关联的值。

SCSS Syntax

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

$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 为空，则返回与 $key 关联的 $map 中的值。

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

SCSS Syntax

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

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

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

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

返回目标地图中与“$keys”中最后一个键关联的值。

返回 null 如果映射没有与键关联的值，或者映射中缺少 $keys 中的任何键或引用了一个不存在的值一张地图。

SCSS Syntax

$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

If $keys is empty, returns whether $map contains a value associated with $key.

SCSS Syntax

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

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

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

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

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

如果不存在，或者地图中缺少 $keys 中的任何键或引用了非地图的值，则返回 false。

SCSS Syntax

$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 中所有键的逗号分隔列表。

SCSS Syntax

$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

⚠️ 注意！

实际上，map.merge($map1, $keys..., $map2) 的实际参数作为 map.merge($map1, $args...) 传递。它们在这里被描述为 $map1, $keys..., $map2 仅用于解释目的。

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

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

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

SCSS Syntax

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

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

如果 $keys 不为空，则跟随 $keys 找到要合并的嵌套映射。如果 $keys 中的任何键从映射中丢失或引用了一个不是映射的值，则将该键的值设置为空映射。

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

SCSS Syntax

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

$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

⚠️ 注意！

实际上，map.set($map, $keys..., $key, $value) 的实际参数作为 map.set($map, $args...) 传递。它们在这里被描述为 $map, $keys..., $key, $value 仅用于解释目的。

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

SCSS Syntax

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

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

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

如果传递了 $keys，则按照 $keys 查找要更新的嵌套映射。如果 $keys 中的任何键从映射中丢失或引用了一个不是映射的值，则将该键的值设置为空映射。

返回 $map 的副本，目标地图在 $key 的值设置为 $value。

SCSS Syntax

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

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

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