sass:list

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

Only Dart Sass currently supports loading built-in modules with @use. Users of other implementations must call functions using their global names instead.

💡 Fun fact:

在 Sass 中，每个映射都被视为一个列表，其中包含每个键/值对的两元素列表。例如，(1: 2, 3: 4) 被视为 (1 2, 3 4)。因此所有这些函数也适用于映射！

单个值也被视为列表。所有这些函数都将 1px 视为包含值 1px 的列表。

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

返回一个将 $val 添加到末尾的 $list 的副本。

如果 $separator 是 comma、space 或 slash，则返回的列表分别是逗号分隔、空格分隔或斜杠分隔。如果是 auto（默认值），返回的列表将使用与 $list 相同的分隔符（如果 $list 没有分隔符，则使用 space）。不允许其他值。

请注意，与 list.join() 不同，如果 $val 是一个列表，它将嵌套在返回的列表中，而不是将其所有元素添加到返回的列表中。

  SCSS

  Sass

      
      Playground
    SCSS Syntax@use 'sass:list';

@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

      
      Playground
    Sass Syntax@use 'sass:list'

@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

返回 $list 中 $value 的索引。

如果 $value 没有出现在 $list 中，则返回 null。如果 $value 在 $list 中出现多次，则返回其第一次出现的索引。

  SCSS

  Sass

      
      Playground
    SCSS Syntax@use 'sass:list';

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

      
      Playground
    Sass Syntax@use 'sass:list'

@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

返回 $list 是否有方括号。

  SCSS

  Sass

      Playground
    SCSS Syntax@use 'sass:list';

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

      Playground
    Sass Syntax@use 'sass:list'

@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

返回一个新列表，其中包含 $list1 的元素，后跟 $list2 的元素。

⚠️ Heads up!

因为单个值被视为单元素列表，所以可以使用 list.join() 在列表末尾添加值。但是，不建议这样做，因为如果该值是一个列表，它将被连接，这可能不是你所期望的。

使用 list.append() 在列表末尾添加单个值。仅在需要将两个列表组合成一个列表时使用 list.join()。

如果 $separator 是 comma、space 或 slash，则返回的列表分别是逗号分隔、空格分隔或斜杠分隔。如果是 auto（默认值），返回的列表将使用 $list1 的分隔符（如果有），否则使用 $list2 的分隔符（如果有），否则使用 space。不允许其他值。

如果 $bracketed 是 auto（默认值），则返回的列表将在 $list1 有方括号时带有方括号。否则，如果 $bracketed 是真值，则返回的列表将有方括号，如果 $bracketed 是假值，则没有方括号。

  SCSS

  Sass

      
      Playground
    SCSS Syntax@use 'sass:list';

@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]

      
      Playground
    Sass Syntax@use 'sass:list'

@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, comma)  // 10px, 20px
@debug list.join((blue, red), (#abc, #def), 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

返回 $list 的长度。

这还可以返回映射中的对数。

  SCSS

  Sass

      
      Playground
    SCSS Syntax@use 'sass:list';

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

      
      Playground
    Sass Syntax@use 'sass:list'

@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

返回 $list 使用的分隔符名称，可以是 space、comma 或 slash。

如果 $list 没有分隔符，则返回 space。

  SCSS

  Sass

      
      Playground
    SCSS Syntax@use 'sass:list';

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

      
      Playground
    Sass Syntax@use 'sass:list'

@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)

返回 $list 中索引为 $n 的索引元素。

如果 $n 是负数，则从 $list 末尾开始计数。如果索引 $n 处没有元素，则抛出错误。

  SCSS

  Sass

      Playground
    SCSS Syntax@use 'sass:list';

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

      Playground
    Sass Syntax@use 'sass:list'

@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

返回 $list 的副本，其中索引为 $n 的元素被 $value 替换。

如果 $n 是负数，则从 $list 末尾开始计数。如果索引 $n 处没有现有元素，则抛出错误。

  SCSS

  Sass

      
      Playground
    SCSS Syntax@use 'sass:list';

@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

      
      Playground
    Sass Syntax@use 'sass:list'

@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

返回一个包含 $elements 的斜杠分隔列表。

⚠️ Heads up!

这是创建斜杠分隔列表的临时解决方案。最终，它们将使用斜杠直接编写，如 1px / 2px / solid，但目前由于斜杠用于除法，在旧语法被移除之前，Sass 无法将其用于新语法。

  SCSS

  Sass

      Playground
    SCSS Syntax@use 'sass:list';

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

      Playground
    Sass Syntax@use 'sass:list'

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

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

将 $lists 中的每个列表组合成一个子列表的单一列表。

返回的列表中的每个元素包含 $lists 中该位置的所有元素。返回的列表的长度与 $lists 中最短的列表一样长。

返回的列表始终是逗号分隔的，子列表始终是空格分隔的。

  SCSS

  Sass

      Playground
    SCSS Syntax@use 'sass:list';

@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

      Playground
    Sass Syntax@use 'sass:list'

@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