sass:selector

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

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

選擇器值選擇器值永久連結

此模組中的函式會檢查和操作選擇器。當它們返回選擇器時，它始終是一個以逗號分隔的列表（選擇器列表），其中包含以空格分隔的列表（複雜選擇器），而這些列表又包含未加引號的字串（複合選擇器）。例如，選擇器 .main aside:hover, .sidebar p 將會返回如下：

@debug ((unquote(".main") unquote("aside:hover")),
        (unquote(".sidebar") unquote("p")));
// .main aside:hover, .sidebar p

傳遞給這些函式的選擇器引數可以採用相同的格式，但它們也可以是普通的字串（加引號或不加引號），或是兩者的組合。例如，".main aside:hover, .sidebar p" 是一個有效的選擇器引數。

selector.is-superselector($super, $sub)
is-superselector($super, $sub) //=> boolean

返回選擇器 $super 是否符合選擇器 $sub 符合的所有元素。

即使 $super 符合的元素比 $sub *更多*，仍然返回 true。

$super 和 $sub 選擇器可以包含佔位選擇器，但不包含父選擇器。

  SCSS

  Sass

       程式碼遊樂場SCSS 語法@use "sass:selector";

@debug selector.is-superselector("a", "a.disabled"); // true
@debug selector.is-superselector("a.disabled", "a"); // false
@debug selector.is-superselector("a", "sidebar a"); // true
@debug selector.is-superselector("sidebar a", "a"); // false
@debug selector.is-superselector("a", "a"); // true

       程式碼遊樂場Sass 語法@use "sass:selector"

@debug selector.is-superselector("a", "a.disabled")  // true
@debug selector.is-superselector("a.disabled", "a")  // false
@debug selector.is-superselector("a", "sidebar a")  // true
@debug selector.is-superselector("sidebar a", "a")  // false
@debug selector.is-superselector("a", "a")  // true

selector.append($selectors...)
selector-append($selectors...) //=> selector

合併 $selectors 而不使用後代組合器，也就是它們之間沒有空格。

如果 $selectors 中的任何選擇器是選擇器列表，則每個複雜選擇器將會單獨合併。

$selectors 可以包含佔位選擇器，但不包含父選擇器。

另請參閱 selector.nest()。

  SCSS

  Sass

       程式碼遊樂場SCSS 語法@use "sass:selector";

@debug selector.append("a", ".disabled"); // a.disabled
@debug selector.append(".accordion", "__copy"); // .accordion__copy
@debug selector.append(".accordion", "__copy, __image");
// .accordion__copy, .accordion__image

       程式碼遊樂場Sass 語法@use "sass:selector"

@debug selector.append("a", ".disabled")  // a.disabled
@debug selector.append(".accordion", "__copy")  // .accordion__copy
@debug selector.append(".accordion", "__copy, __image")
// .accordion__copy, .accordion__image

selector.extend($selector, $extendee, $extender)
selector-extend($selector, $extendee, $extender) //=> selector

如同使用 @extend 規則一樣擴展 $selector。

返回修改後的 $selector 副本，其中包含以下 @extend 規則

#{$extender} {
  @extend #{$extendee};
}

換句話說，將 $selector 中所有 $extendee 的實例替換為 $extendee, $extender。如果 $selector 不包含 $extendee，則按原樣返回。

$selector、$extendee 和 $extender 選擇器可以包含佔位符選擇器，但不包含父選擇器。

另請參閱 selector.replace()。

  SCSS

  Sass

       程式碼遊樂場SCSS 語法@use "sass:selector";

@debug selector.extend("a.disabled", "a", ".link"); // a.disabled, .link.disabled
@debug selector.extend("a.disabled", "h1", "h2"); // a.disabled
@debug selector.extend(".guide .info", ".info", ".content nav.sidebar");
// .guide .info, .guide .content nav.sidebar, .content .guide nav.sidebar

       程式碼遊樂場Sass 語法@use "sass:selector"

@debug selector.extend("a.disabled", "a", ".link")  // a.disabled, .link.disabled
@debug selector.extend("a.disabled", "h1", "h2")  // a.disabled
@debug selector.extend(".guide .info", ".info", ".content nav.sidebar")
// .guide .info, .guide .content nav.sidebar, .content .guide nav.sidebar

selector.nest($selectors...)
selector-nest($selectors...) //=> selector

合併 $selectors，如同它們在樣式表中彼此嵌套一樣。

$selectors 可以包含佔位符選擇器。與其他選擇器函數不同，除了第一個以外，所有選擇器也可以包含父選擇器。

另請參閱 selector.append()。

  SCSS

  Sass

       程式碼遊樂場SCSS 語法@use "sass:selector";

@debug selector.nest("ul", "li"); // ul li
@debug selector.nest(".alert, .warning", "p"); // .alert p, .warning p
@debug selector.nest(".alert", "&:hover"); // .alert:hover
@debug selector.nest(".accordion", "&__copy"); // .accordion__copy

       程式碼遊樂場Sass 語法@use "sass:selector"

@debug selector.nest("ul", "li")  // ul li
@debug selector.nest(".alert, .warning", "p")  // .alert p, .warning p
@debug selector.nest(".alert", "&:hover")  // .alert:hover
@debug selector.nest(".accordion", "&__copy")  // .accordion__copy

selector.parse($selector)
selector-parse($selector) //=> selector

以選擇器值格式返回 $selector。

  SCSS

  Sass

       程式碼遊樂場SCSS 語法@use "sass:selector";

@debug selector.parse(".main aside:hover, .sidebar p");
// ((unquote(".main") unquote("aside:hover")),
//  (unquote(".sidebar") unquote("p")))

       程式碼遊樂場Sass 語法@use "sass:selector"

@debug selector.parse(".main aside:hover, .sidebar p")
// ((unquote(".main") unquote("aside:hover")),
//  (unquote(".sidebar") unquote("p")))

selector.replace($selector, $original, $replacement)
selector-replace($selector, $original, $replacement) //=> selector

返回 $selector 的副本，其中所有 $original 的實例都替換為 $replacement。

這使用 @extend 規則的智慧型統一來確保 $replacement 無縫整合到 $selector 中。如果 $selector 不包含 $original，則按原樣返回。

$selector、$original 和 $replacement 選擇器可以包含佔位符選擇器，但不包含父選擇器。

另請參閱 selector.extend()。

  SCSS

  Sass

       程式碼遊樂場SCSS 語法@use "sass:selector";

@debug selector.replace("a.disabled", "a", ".link"); // .link.disabled
@debug selector.replace("a.disabled", "h1", "h2"); // a.disabled
@debug selector.replace(".guide .info", ".info", ".content nav.sidebar");
// .guide .content nav.sidebar, .content .guide nav.sidebar

       程式碼遊樂場Sass 語法@use "sass:selector"

@debug selector.replace("a.disabled", "a", ".link")  // .link.disabled
@debug selector.replace("a.disabled", "h1", "h2")  // a.disabled
@debug selector.replace(".guide .info", ".info", ".content nav.sidebar")
// .guide .content nav.sidebar, .content .guide nav.sidebar

selector.unify($selector1, $selector2)
selector-unify($selector1, $selector2) //=> selector | null

返回僅匹配 $selector1 和 $selector2 *都* 匹配的元素的選擇器。

如果 $selector1 和 $selector2 沒有匹配任何相同的元素，或者沒有選擇器可以表達它們的重疊部分，則返回 null。

與 @extend 規則生成的選擇器類似，如果 $selector1 和 $selector2 都是複雜選擇器，則返回的選擇器不保證匹配 *所有* 由 $selector1 和 $selector2 匹配的元素。

  SCSS

  Sass

       程式碼遊樂場SCSS 語法@use "sass:selector";

@debug selector.unify("a", ".disabled"); // a.disabled
@debug selector.unify("a.disabled", "a.outgoing"); // a.disabled.outgoing
@debug selector.unify("a", "h1"); // null
@debug selector.unify(".warning a", "main a"); // .warning main a, main .warning a

       程式碼遊樂場Sass 語法@use "sass:selector"

@debug selector.unify("a", ".disabled")  // a.disabled
@debug selector.unify("a.disabled", "a.outgoing")  // a.disabled.outgoing
@debug selector.unify("a", "h1")  // null
@debug selector.unify(".warning a", "main a")  // .warning main a, main .warning a

selector.simple-selectors($selector)
simple-selectors($selector) //=> list

返回 $selector 中的簡單選擇器列表。

$selector 必須是包含複合選擇器的單個字串。這表示它不能包含組合符號（包括空格）或逗號。

返回的列表以逗號分隔，且簡單選擇器是不帶引號的字串。

  SCSS

  Sass

       程式碼遊樂場SCSS 語法@use "sass:selector";

@debug selector.simple-selectors("a.disabled"); // a, .disabled
@debug selector.simple-selectors("main.blog:after"); // main, .blog, :after

       程式碼遊樂場Sass 語法@use "sass:selector"

@debug selector.simple-selectors("a.disabled")  // a, .disabled
@debug selector.simple-selectors("main.blog:after")  // main, .blog, :after