sass:list

Dart Sass: 自 1.23.0 版本起
LibSass: ✗
Ruby Sass: ✗

目前只有 Dart Sass 支援使用 @use 載入內建模組。其他實作的使用者必須改用全域名稱呼叫函式。

💡 小知識

在 Sass 中，每個映射都被視為一個列表，其中包含每個鍵/值對的兩個元素列表。例如，(1: 2, 3: 4) 等同於 (1 2, 3 4)。所以所有這些函式也適用於映射！

個別值也被視為列表。所有這些函式都將 1px 視為包含值 1px 的列表。

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

傳回 $list 的副本，並將 $val 新增至末尾。

如果 $separator 是 comma、space 或 slash，則傳回的列表分別以逗號、空格或斜線分隔。如果是 auto（預設值），則傳回的列表將使用與 $list 相同的分隔符號（如果 $list 沒有分隔符號，則使用空格）。不允許其他值。

請注意，與 list.join() 不同，如果 $val 是一個列表，它會被嵌套在傳回的列表中，而不是將其所有元素都新增至傳回的列表。

  SCSS

  Sass

       程式碼遊樂場SCSS 語法@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

       程式碼遊樂場Sass 語法@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

傳回 $value 在 $list 中的索引。

如果 $value 沒有出現在 $list 中，則回傳 null。如果 $value 在 $list 中出現多次，則回傳其第一次出現的索引值。

  SCSS

  Sass

       程式碼遊樂場SCSS 語法@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

       程式碼遊樂場Sass 語法@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

       程式碼遊樂場SCSS 語法@use 'sass:list';

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

       程式碼遊樂場Sass 語法@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 的元素。

⚠️ 注意！

由於個別值會被視為單元素列表，因此可以使用 list.join() 將值新增到列表的末端。然而，*不建議這樣做*，因為如果該值是一個列表，它將會被串接，這可能不是您預期的結果。

請改用 list.append() 將單個值新增到列表中。僅使用 list.join() 將兩個列表合併成一個。

如果 $separator 是 comma、space 或 slash，則回傳的列表分別以逗號、空格或斜線分隔。如果是 auto（預設值），回傳的列表將使用與 $list1 相同的分隔符號（如果它有分隔符號），否則使用 $list2 的分隔符號（如果它有分隔符號），否則使用 space。不允許其他值。

如果 $bracketed 是 auto（預設值），則回傳的列表將會加上括號（如果 $list1 有括號）。否則，如果 $bracketed 是真值，回傳的列表將會有方括號；如果 $bracketed 是假值，則沒有括號。

  SCSS

  Sass

       程式碼遊樂場SCSS 語法@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]

       程式碼遊樂場Sass 語法@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 的長度。

這也可以回傳映射（map）中的鍵值對數量。

  SCSS

  Sass

       程式碼遊樂場SCSS 語法@use 'sass:list';

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

       程式碼遊樂場Sass 語法@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

       程式碼遊樂場SCSS 語法@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

       程式碼遊樂場Sass 語法@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

       程式碼遊樂場SCSS 語法@use 'sass:list';

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

       程式碼遊樂場Sass 語法@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

       程式碼遊樂場SCSS 語法@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

       程式碼遊樂場Sass 語法@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。

⚠️ 注意！

此函式是用於建立以斜線分隔列表的臨時解決方案。最終，它們將會以斜線直接撰寫，例如 1px / 2px / solid，但目前斜線用於除法，因此在舊語法移除之前，Sass 無法將其用於新語法。

  SCSS

  Sass

       程式碼遊樂場SCSS 語法@use 'sass:list';

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

       程式碼遊樂場Sass 語法@use 'sass:list'

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

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

將 $lists 中的每個列表合併成一個子列表的列表。

回傳列表中的每個元素都包含 $lists 中該位置的所有元素。回傳列表的長度與 $lists 中最短的列表相同。

回傳的列表一律以逗號分隔，子列表一律以空格分隔。

  SCSS

  Sass

       程式碼遊樂場SCSS 語法@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

       程式碼遊樂場Sass 語法@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