sass:list

Compatibilidade:
Sass de Dart
since 1.23.0
LibSass
✗
Sass de Ruby
✗

💡 Fato Divertido:

Na Sass, todo mapa conta como uma lista que contém uma lista de dois elementos para cada par de chave e valor. Por exemplo, (1: 2, 3: 4) conta como (1 2, 3 4). Todas estas funções também funcionam para os mapas!

Os valores individuais também contam como listas. Todas estas funções tratam 1px como uma lista que contém o valor 1px.

list.append($list, $val, $separator: auto)
append($list, $val, $separator: auto) //=> list

Retorna uma cópia de $list com $val adicionado ao final.

Se $separator for comma, space, ou slash, a lista retornada é separada por vírgula, separada por espaço, ou separada por barra, respetivamente. Se for auto (o padrão), a lista retornada usará o mesmo separador que a $list (ou space se $list não tiver um separador). Outros valores não são permitidos.

Nota que ao contrário de list.join(), se $val for uma lista é encaixada dentro da lista retornada no lugar de ter todos os seus elementos adicionados à lista retornada:

SCSS Syntax

@debug list.append(10px 20px, 30px); // 10px 20px 30px
@debug list.append((blue, red), green); // blue, red, green
@debug list.append(10px 20px, 30px 40px); // 10px 20px (30px 40px)
@debug list.append(10px, 20px, $separator: comma); // 10px, 20px
@debug list.append((blue, red), green, $separator: space); // blue red green

list.index($list, $value)
index($list, $value) //=> number | null

Retorna o índice do $value no $list.

Se $value não aparecer na $list, este retorna null. Se $value aparecer várias vezes na $list, esta retorna o índice do seu primeiro aparecimento:

SCSS Syntax

@debug list.index(1px solid red, 1px); // 1
@debug list.index(1px solid red, solid); // 2
@debug list.index(1px solid red, dashed); // null

list.is-bracketed($list)
is-bracketed($list) //=> boolean

Retorna verdadeiro se $list tiver parênteses reto:

SCSS Syntax

@debug list.is-bracketed(1px 2px 3px); // false
@debug list.is-bracketed([1px, 2px, 3px]); // true

list.join($list1, $list2, $separator: auto, $bracketed: auto)
join($list1, $list2, $separator: auto, $bracketed: auto) //=> list

Retorna uma nova lista contendo os elementos de $list1 seguido pelos elementos de $list2.

⚠️ Atenção!

Uma vez que valores individuais contam como listas de um elemento, é possível usar list.join() para adicionar um valor no final duma lista. No entanto, isto não é recomendado, uma vez que se este valor for uma lista será concatenado, o que é provavelmente o que estás a espera.

Use list.append() para adicionar um único valor à uma lista. Apenas use list.join() para combinar duas listas numa.

Se $separator for comma, space, ou slash, a lista retornada é separada por vírgula, separada por espaço, ou separada por barra, respetivamente. Se for auto (o padrão), a lista retornada usará o mesmo separador que a $list1 se esta tiver um separador, ou $list2 se esta tiver um separador, ou então space. Outros valores não são permitidos.

Se $bracketed for auto (o padrão), a lista retornada será envolvida em parênteses se $list estiver. De outro modo, a lista retornada terá parênteses reto se $bracketed for verdadeiro e sem parênteses se $bracketed for falso:

SCSS Syntax

@debug list.join(10px 20px, 30px 40px); // 10px 20px 30px 40px
@debug list.join((blue, red), (#abc, #def)); // blue, red, #abc, #def
@debug list.join(10px, 20px); // 10px 20px
@debug list.join(10px, 20px, $separator: comma); // 10px, 20px
@debug list.join((blue, red), (#abc, #def), $separator: space); // blue red #abc #def
@debug list.join([10px], 20px); // [10px 20px]
@debug list.join(10px, 20px, $bracketed: true); // [10px 20px]

list.length($list)
length($list) //=> number

Retorna o comprimento da $list.

Este também pode retornar o número de pares num mapa.

SCSS Syntax

@debug list.length(10px); // 1
@debug list.length(10px 20px 30px); // 3
@debug list.length((width: 10px, height: 20px)); // 2

list.separator($list)
list-separator($list) //=> unquoted string

Retorna o nome do separador usado pela $list, ou space, comma, ou slash.

Se $list não tiver um separador, retorna space.

SCSS Syntax

@debug list.separator(1px 2px 3px); // space
@debug list.separator(1px, 2px, 3px); // comma
@debug list.separator('Helvetica'); // space
@debug list.separator(()); // space

list.nth($list, $n)
nth($list, $n)

Retorna o elemento da $list no índice $n.

Se $n for negativo, conta a partir do final da $list. Lança um erro se não existir nenhum elemento no índice $n.

SCSS Syntax

@debug list.nth(10px 12px 16px, 2); // 12px
@debug list.nth([line1, line2, line3], -1); // line3

list.set-nth($list, $n, $value)
set-nth($list, $n, $value) //=> list

Retorna uma cópia de $list com o elemento no índice $n substituído por $value.

Se $n for negativo, conta a partir do final da $list. Lança um erro se não existir nenhum elemento no índice $n.

SCSS Syntax

@debug list.set-nth(10px 20px 30px, 1, 2em); // 2em 20px 30px
@debug list.set-nth(10px 20px 30px, -1, 8em); // 10px, 20px, 8em
@debug list.set-nth((Helvetica, Arial, sans-serif), 3, Roboto); // Helvetica, Arial, Roboto

list.slash($elements...) //=> list

Retorna uma lista separada por barra que contém $elements.

⚠️ Atenção!

Esta função é uma solução temporária para criação de listas separadas por barra. Eventualmente, serão escritas literalmente com barras, como em 1px / 2px / solid, mas por enquanto as barras são usadas para divisão então a Sass não pode usá-los para a nova sintaxe até a antiga sintaxe ser removida.

SCSS Syntax

@debug list.slash(1px, 50px, 100px); // 1px / 50px / 100px

list.zip($lists...)
zip($lists...) //=> list

Combina todas as listas em $lists numa única lista de sub-listas.

Cada elemento na lista retornada contém todos os elementos naquela posição na $lists. A lista retornada é tão longa quanto a lista mais curta em $lists.

A lista retornada é sempre separada por vírgula e as sub-listas são sempre separadas por espaço.

SCSS Syntax

@debug list.zip(10px 50px 100px, short mid long); // 10px short, 50px mid, 100px long
@debug list.zip(10px 50px 100px, short mid); // 10px short, 50px mid