mirror of
https://github.com/danog/sass-site.git
synced 2024-12-05 21:39:02 +01:00
192 lines
6.4 KiB
Plaintext
192 lines
6.4 KiB
Plaintext
---
|
|
title: Maps
|
|
table_of_contents: true
|
|
---
|
|
|
|
{% markdown %}
|
|
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](/documentation/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](/documentation/values/lists), maps *must* be written with parentheses
|
|
around them. A map with no pairs is written `()`.
|
|
|
|
{% funFact %}
|
|
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)`.
|
|
{% endfunFact %}
|
|
|
|
Maps allow any Sass values to be used as their keys. The [`==` operator][] is
|
|
used to determine whether two keys are the same.
|
|
|
|
[`==` operator]: /documentation/operators/equality
|
|
|
|
{% headsUp %}
|
|
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]: /documentation/values/strings#quoted
|
|
[unquoted strings]: /documentation/values/strings#unquoted
|
|
{% endheadsUp %}
|
|
|
|
## 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.
|
|
|
|
[functions]: /documentation/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]: /documentation/modules/map#get
|
|
[`null`]: /documentation/values/null
|
|
{% endmarkdown %}
|
|
|
|
{% render 'code_snippets/example-map-get' %}
|
|
|
|
{% markdown %}
|
|
### 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]: /documentation/at-rules/control/each
|
|
{% endmarkdown %}
|
|
|
|
{% render 'code_snippets/example-each-map' %}
|
|
|
|
{% markdown %}
|
|
### 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.set($map, $key, $value)` function][] does this: it
|
|
returns a copy of `$map` with the value at `$key` set to `$value`.
|
|
|
|
[`map.set($map, $key, $value)` function]: /documentation/modules/map#set
|
|
{% endmarkdown %}
|
|
|
|
{% codeExample 'maps', false %}
|
|
@use "sass:map";
|
|
|
|
$font-weights: ("regular": 400, "medium": 500, "bold": 700);
|
|
|
|
@debug map.set($font-weights, "extra-bold", 900);
|
|
// ("regular": 400, "medium": 500, "bold": 700, "extra-bold": 900)
|
|
@debug map.set($font-weights, "bold", 900);
|
|
// ("regular": 400, "medium": 500, "bold": 900)
|
|
===
|
|
@use "sass:map"
|
|
|
|
$font-weights: ("regular": 400, "medium": 500, "bold": 700)
|
|
|
|
@debug map.set($font-weights, "extra-bold": 900)
|
|
// ("regular": 400, "medium": 500, "bold": 700, "extra-bold": 900)
|
|
@debug map.set($font-weights, "bold", 900)
|
|
// ("regular": 400, "medium": 500, "bold": 900)
|
|
{% endcodeExample %}
|
|
|
|
{% markdown %}
|
|
Instead of setting values one-by-one, you can also merge two existing maps
|
|
using [`map.merge($map1, $map2)`][].
|
|
|
|
[`map.merge($map1, $map2)`]: /documentation/modules/map#merge
|
|
{% endmarkdown %}
|
|
|
|
{% codeExample 'map-merge', false %}
|
|
@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)
|
|
{% endcodeExample %}
|
|
|
|
{% markdown %}
|
|
If both maps have the same keys, the second map's values are used in the map
|
|
that gets returned.
|
|
{% endmarkdown %}
|
|
|
|
{% codeExample 'map-same-keys', false %}
|
|
@use "sass:map";
|
|
|
|
$weights: ("light": 300, "medium": 500);
|
|
|
|
@debug map.merge($weights, ("medium": 700));
|
|
// ("light": 300, "medium": 700)
|
|
===
|
|
@use "sass:map";
|
|
|
|
$weights: ("light": 300, "medium": 500)
|
|
|
|
@debug map.merge($weights, ("medium": 700))
|
|
// ("light": 300, "medium": 700)
|
|
{% endcodeExample %}
|
|
|
|
{% markdown %}
|
|
Note that because Sass maps are [immutable][], `map.set()` and `map.merge()`
|
|
do not 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.
|
|
{% endmarkdown %}
|
|
|
|
{% codeExample 'immutability', false %}
|
|
@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)) !global;
|
|
}
|
|
|
|
@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)) !global
|
|
|
|
|
|
@include add-browser-prefix("opera", o)
|
|
@debug $prefixes-by-browser
|
|
// ("firefox": moz, "safari": webkit, "ie": ms, "opera": o)
|
|
{% endcodeExample %}
|