sass:map

相容性
Dart Sass
自 1.23.0 起
LibSass
✗
Ruby Sass
✗

目前只有 Dart Sass 支援使用 @use 載入內建模組。其他實作的使用者必須改用全域名稱呼叫函式。

💡 小知識

Sass 函式庫和設計系統傾向於共用和覆寫以巢狀映射（包含映射的映射，其中又包含映射）表示的設定。

為了協助您使用巢狀映射，一些映射函式支援深度操作。例如，如果您傳遞多個鍵給 map.get()，它將會依循這些鍵找到所需的巢狀映射。

程式碼遊樂場

SCSS 語法

@use "sass:map";

$config: (a: (b: (c: d)));
@debug map.get($config, a, b, c); // d
程式碼遊樂場

Sass 語法

@use "sass:map"

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

map.deep-merge($map1, $map2) //=> map
相容性
Dart Sass
自 1.27.0 起
LibSass
✗
Ruby Sass
✗

與 map.merge() 相同，但巢狀映射值也會遞迴合併。

程式碼遊樂場

SCSS 語法

@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
//   )
// )
程式碼遊樂場

Sass 語法

@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
自 1.27.0 起
LibSass
✗
Ruby Sass
✗

如果 $keys 為空，則返回 $map 的副本，且不與 $key 關聯任何值。

程式碼遊樂場

SCSS 語法

@use "sass:map";

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

@debug map.deep-remove($font-weights, "regular");
// ("medium": 500, "bold": 700)
程式碼遊樂場

Sass 語法

@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 語法

@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
//     )
//   )
// )
程式碼遊樂場

Sass 語法

@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 語法

@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
程式碼遊樂場

Sass 語法

@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
自 1.27.0 起
LibSass
✗
Ruby Sass
✗

只有 Dart Sass 支援以兩個以上引數呼叫 map.get()。

如果 $keys 不為空，則按照從左到右的順序，依循包含 $key 並排除 $keys 中最後一個鍵的鍵集，找到要搜尋的巢狀映射。

返回目標映射中與 $keys 中最後一個鍵關聯的值。

如果映射中沒有與鍵關聯的值，或者 $keys 中的任何鍵在映射中缺失或引用了非映射的值，則返回 null。

程式碼遊樂場

SCSS 語法

@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
程式碼遊樂場

Sass 語法

@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 語法

@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
程式碼遊樂場

Sass 語法

@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
自 1.27.0 起
LibSass
✗
Ruby Sass
✗

只有 Dart Sass 支援以兩個以上引數呼叫 map.has-key()。

如果 $keys 不為空，則按照從左到右的順序，依循包含 $key 並排除 $keys 中最後一個鍵的鍵集，找到要搜尋的巢狀映射。

如果目標映射包含與 $keys 中最後一個鍵關聯的值，則返回 true。

如果沒有，或者 $keys 中的任何鍵在映射中缺失或引用了非映射的值，則返回 false。

程式碼遊樂場

SCSS 語法

@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
程式碼遊樂場

Sass 語法

@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 中所有鍵的逗號分隔列表。

程式碼遊樂場

SCSS 語法

@use "sass:map";

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

@debug map.keys($font-weights); // "regular", "medium", "bold"
程式碼遊樂場

Sass 語法

@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

⚠️ 注意！

實際應用中，傳遞給 map.merge($map1, $keys..., $map2) 的實際引數是 map.merge($map1, $args...) 的形式。這裡將其描述為 $map1, $keys..., $map2 僅用於說明目的。

如果沒有傳遞 $keys，則返回一個包含 $map1 和 $map2 中所有鍵值的新映射。

如果 $map1 和 $map2 具有相同的鍵，則 $map2 的值優先。

返回映射中所有同時出現在 $map1 中的鍵，其順序與 $map1 中的順序相同。來自 $map2 的新鍵會出現在映射的末尾。

程式碼遊樂場

SCSS 語法

@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)
程式碼遊樂場

Sass 語法

@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
自 1.27.0 起
LibSass
✗
Ruby Sass
✗

只有 Dart Sass 支援以兩個以上引數呼叫 map.merge()。

如果 $keys 不為空，則依循 $keys 找到要合併的巢狀映射。如果 $keys 中的任何鍵在映射中缺失或引用了非映射的值，則將該鍵的值設置為空映射。

返回 $map1 的副本，其中目標映射被一個包含目標映射和 $map2 中所有鍵值的新映射取代。

程式碼遊樂場

SCSS 語法

@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
//     )
//   )
// )
程式碼遊樂場

Sass 語法

@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 關聯的任何值。

如果 $keys 中的鍵在 $map 中沒有關聯的值，則會被忽略。

程式碼遊樂場

SCSS 語法

@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)
程式碼遊樂場

Sass 語法

@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

⚠️ 注意！

實際應用中，傳遞給 map.set($map, $keys..., $key, $value) 的實際引數是 map.set($map, $args...) 的形式。這裡將其描述為 $map, $keys..., $key, $value 僅用於說明目的。

如果沒有傳遞 $keys，則返回 $map 的副本，其中 $key 的值設置為 $value。

程式碼遊樂場

SCSS 語法

@use "sass:map";

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

@debug map.set($font-weights, "regular", 300);
// ("regular": 300, "medium": 500, "bold": 700)
程式碼遊樂場

Sass 語法

@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
自 1.27.0 起
LibSass
✗
Ruby Sass
✗

只有 Dart Sass 支援以三個以上引數呼叫 map.set()。

如果傳遞了 $keys，則依循 $keys 找到要更新的巢狀映射。如果 $keys 中的任何鍵在映射中缺失或引用了非映射的值，則將該鍵的值設置為空映射。

返回 $map 的副本，其中目標映射在 $key 處的值設置為 $value。

程式碼遊樂場

SCSS 語法

@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
//     )
//   )
// )
程式碼遊樂場

Sass 語法

@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 中所有值的逗號分隔列表。

程式碼遊樂場

SCSS 語法

@use "sass:map";

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

@debug map.values($font-weights); // 400, 500, 700
程式碼遊樂場

Sass 語法

@use "sass:map"

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

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