mirror of
https://github.com/danog/sass-site.git
synced 2024-12-04 18:38:12 +01:00
135 lines
4.4 KiB
Plaintext
135 lines
4.4 KiB
Plaintext
---
|
|
title: Maps
|
|
---
|
|
|
|
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][]
|
|
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][], maps *must* be written with parentheses around them. A map with no
|
|
pairs is written `()`.
|
|
|
|
[expression]: ../syntax/structure#expressions
|
|
[lists]: lists
|
|
|
|
<% 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]: ../functions/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.
|
|
|
|
the [`map-get($map, $key)` function]: ../functions/map#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.
|
|
|
|
The [`@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]: ../functions/map#map-merge
|
|
|
|
<% example(autogen_css: false) do %>
|
|
$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
|
|
// )
|
|
===
|
|
$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 %>
|
|
$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)
|
|
===
|
|
$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 %>
|
|
$font-weights: ("regular": 400, "medium": 500, "bold": 700);
|
|
|
|
@debug map-merge($font-weights, ("medium": 600));
|
|
// ("regular": 400, "medium": 600, "bold": 700)
|
|
===
|
|
$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
|