mirror of
https://github.com/danog/sass-site.git
synced 2024-12-13 09:57:35 +01:00
b1b07540f2
Closes #363
182 lines
5.7 KiB
Plaintext
182 lines
5.7 KiB
Plaintext
---
|
|
title: Maps
|
|
table_of_contents: true
|
|
---
|
|
|
|
Maps in Sass hold pairs of keys and values, and make it easy to look up a value
|
|
by its corresponding key. They're written `(<expression>: <expression>,
|
|
<expression>: <expression>)`. The [expression](../syntax/structure#expressions)
|
|
before the `:` is the key, and the expression after is the value associated with
|
|
that key. The keys must be unique, but the values may be duplicated. Unlike
|
|
[lists](lists), maps *must* be written with parentheses around them. A map with
|
|
no pairs is written `()`.
|
|
|
|
<% fun_fact do %>
|
|
Astute readers may note that an empty map, `()`, is written the same as an
|
|
empty list. That's because it counts as both a map and a list. In fact, *all*
|
|
maps count as lists! Every map counts as a list that contains a two-element
|
|
list for each key/value pair. For example, `(1: 2, 3: 4)` counts as `(1 2, 3
|
|
4)`.
|
|
<% end %>
|
|
|
|
Maps allow any Sass values to be used as their keys. The [`==` operator][] is
|
|
used to determine whether two keys are the same.
|
|
|
|
[`==` operator]: ../operators/equality
|
|
|
|
<% heads_up do %>
|
|
Most of the time, it's a good idea to use [quoted strings][] rather than
|
|
[unquoted strings][] for map keys. This is because some values, such as color
|
|
names, may *look* like unquoted strings but actually be other types. To avoid
|
|
confusing problems down the line, just use quotes!
|
|
|
|
[quoted strings]: strings#quoted
|
|
[unquoted strings]: strings#unquoted
|
|
<% end %>
|
|
|
|
## Using Maps
|
|
|
|
Since maps aren't valid CSS values, they don't do much of anything on their own.
|
|
That's why Sass provides a bunch of [functions][] to create maps and access the
|
|
values they contain. With
|
|
|
|
[functions]: ../modules/map
|
|
|
|
### Look Up a Value
|
|
|
|
Maps are all about associating keys and values, so naturally there's a way to
|
|
get the value associated with a key: the [`map.get($map, $key)` function][]!
|
|
This function returns the value in the map associated with the given key. It
|
|
returns [`null`][] if the map doesn't contain the key.
|
|
|
|
[`map.get($map, $key)` function]: ../modules/map#get
|
|
[`null`]: null
|
|
|
|
<%= partial 'code-snippets/example-map-get' %>
|
|
|
|
### Do Something for Every Pair
|
|
|
|
This doesn't actually use a function, but it's still one of the most common ways
|
|
to use maps. The [`@each` rule][] evaluates a block of styles for each key/value
|
|
pair in a map. The key and the value are assigned to variables so they can
|
|
easily be accessed in the block.
|
|
|
|
[`@each` rule]: ../at-rules/control/each
|
|
|
|
<%= partial 'code-snippets/example-each-map' %>
|
|
|
|
### Add to a Map
|
|
|
|
It's also useful to add new pairs to a map, or to replace the value for an
|
|
existing key. The [`map.merge($map1, $map2)` function][] does this: it returns a
|
|
new map that contains all the key/value pairs in *both* arguments.
|
|
|
|
[`map.merge($map1, $map2)` function]: ../modules/map#merge
|
|
|
|
<% example(autogen_css: false) do %>
|
|
@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
|
|
// )
|
|
===
|
|
@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
|
|
// )
|
|
<% end %>
|
|
|
|
`map.merge()` is often used with an inline map to add a single key/value pair.
|
|
|
|
<% example(autogen_css: false) do %>
|
|
@use "sass:map";
|
|
|
|
$font-weights: ("regular": 400, "medium": 500, "bold": 700);
|
|
|
|
@debug map.merge($font-weights, ("extra-bold": 900));
|
|
// ("regular": 400, "medium": 500, "bold": 700, "extra-bold": 900)
|
|
===
|
|
@use "sass:map"
|
|
|
|
$font-weights: ("regular": 400, "medium": 500, "bold": 700)
|
|
|
|
@debug map.merge($font-weights, ("extra-bold": 900))
|
|
// ("regular": 400, "medium": 500, "bold": 700, "extra-bold": 900)
|
|
<% end %>
|
|
|
|
If both maps have the same keys, the second map's values are used in the map
|
|
that gets returned.
|
|
|
|
<% example(autogen_css: false) do %>
|
|
@use "sass:map";
|
|
|
|
$font-weights: ("regular": 400, "medium": 500, "bold": 700);
|
|
|
|
@debug map.merge($font-weights, ("medium": 600));
|
|
// ("regular": 400, "medium": 600, "bold": 700)
|
|
===
|
|
@use "sass:map"
|
|
|
|
$font-weights: ("regular": 400, "medium": 500, "bold": 700)
|
|
|
|
@debug map.merge($font-weights, ("medium": 600))
|
|
// ("regular": 400, "medium": 600, "bold": 700)
|
|
<% end %>
|
|
|
|
Note that because Sass maps are [immutable][], `map.merge()` doesn't modify the
|
|
original list.
|
|
|
|
[immutable]: #immutability
|
|
|
|
## Immutability
|
|
|
|
Maps in Sass are *immutable*, which means that the contents of a map value never
|
|
changes. Sass's map functions all return new maps rather than modifying the
|
|
originals. Immutability helps avoid lots of sneaky bugs that can creep in when
|
|
the same map is shared across different parts of the stylesheet.
|
|
|
|
You can still update your state over time by assigning new maps to the same
|
|
variable, though. This is often used in functions and mixins to track
|
|
configuration in a map.
|
|
|
|
<% example(autogen_css: false) do %>
|
|
@use "sass:map";
|
|
|
|
$prefixes-by-browser: ("firefox": moz, "safari": webkit, "ie": ms);
|
|
|
|
@mixin add-browser-prefix($browser, $prefix) {
|
|
$prefixes-by-browser: map.merge($prefixes-by-browser, ($browser: $prefix));
|
|
}
|
|
|
|
@include add-browser-prefix("opera", o);
|
|
@debug $prefixes-by-browser;
|
|
// ("firefox": moz, "safari": webkit, "ie": ms, "opera": o)
|
|
===
|
|
@use "sass:map";
|
|
|
|
$prefixes-by-browser: ("firefox": moz, "safari": webkit, "ie": ms)
|
|
|
|
@mixin add-browser-prefix($browser, $prefix)
|
|
$prefixes-by-browser: map.merge($prefixes-by-browser, ($browser: $prefix))
|
|
|
|
|
|
@include add-browser-prefix("opera", o)
|
|
@debug $prefixes-by-browser
|
|
// ("firefox": moz, "safari": webkit, "ie": ms, "opera": o)
|
|
<% end %>
|