sass:selector

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.

选择器值选择器值 permalink

¥Selector Values

该模块中的函数检查和操作选择器。每当它们返回选择器时，它始终是一个逗号分隔的列表（选择器列表），其中包含空格分隔的列表（复杂选择器），而列表又包含不带引号的字符串（复合选择器）。例如，选择器 .main aside:hover, .sidebar p 将返回为：

¥The functions in this module inspect and manipulate selectors. Whenever they return a selector, it’s always a comma-separated list (the selector list) that contains space-separated lists (the complex selectors) that contain unquoted strings (the compound selectors). For example, the selector .main aside:hover, .sidebar p would be returned as:

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

这些函数的选择器参数可以采用相同的格式，但它们也可以只是普通字符串（带引号或不带引号）或组合。例如，".main aside:hover, .sidebar p" 是有效的选择器参数。

¥Selector arguments to these functions may be in the same format, but they can also just be normal strings (quoted or unquoted), or a combination. For example, ".main aside:hover, .sidebar p" is a valid selector argument.

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

返回选择器 $super 是否匹配选择器 $sub 匹配的所有元素。

¥Returns whether the selector $super matches all the elements that the selector $sub matches.

即使 $super 匹配的元素多于 $sub，仍然返回 true。

¥Still returns true even if $super matches more elements than $sub.

$super 和 $sub 选择器可以包含占位符选择器，但不能包含父选择器。

¥The $super and $sub selectors may contain placeholder selectors, but not parent selectors.

  SCSS

  Sass

      
      Playground
    SCSS Syntax@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

      
      Playground
    Sass Syntax@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 与后代组合器组合在一起，即它们之间没有空格。

¥Combines $selectors without descendant combinators—that is, without whitespace between them.

如果 $selectors 中的任何选择器是选择器列表，则每个复杂选择器被单独组合。

¥If any selector in $selectors is a selector list, each complex selector is combined separately.

$selectors 可以包含占位符选择器，但不能包含父选择器。

¥The $selectors may contain placeholder selectors, but not parent selectors.

另见 selector.nest()。

¥See also selector.nest().

  SCSS

  Sass

      
      Playground
    SCSS Syntax@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

      
      Playground
    Sass Syntax@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。

¥Extends $selector as with the @extend rule.

返回使用以下 @extend 规则修改的 $selector 的副本：

¥Returns a copy of $selector modified with the following @extend rule:

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

换句话说，将 $selector 中 $extendee 的所有实例替换为 $extendee, $extender。如果 $selector 不包含 $extendee，则按原样返回。

¥In other words, replaces all instances of $extendee in $selector with $extendee, $extender. If $selector doesn’t contain $extendee, returns it as-is.

$selector、$extendee 和 $extender 选择器可以包含占位符选择器，但不能包含父选择器。

¥The $selector, $extendee, and $extender selectors may contain placeholder selectors, but not parent selectors.

另见 selector.replace()。

¥See also selector.replace().

  SCSS

  Sass

      
      Playground
    SCSS Syntax@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

      
      Playground
    Sass Syntax@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，就好像它们在样式表中相互嵌套一样。

¥Combines $selectors as though they were nested within one another in the stylesheet.

$selectors 可以包含占位符选择器。与其他选择器函数不同，除了第一个之外的所有选择器函数也可能包含父选择器。

¥The $selectors may contain placeholder selectors. Unlike other selector functions, all of them except the first may also contain parent selectors.

另见 selector.append()。

¥See also selector.append().

  SCSS

  Sass

      
      Playground
    SCSS Syntax@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

      
      Playground
    Sass Syntax@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。

¥Returns $selector in the selector value format.

  SCSS

  Sass

      
      Playground
    SCSS Syntax@use "sass:selector";

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

      
      Playground
    Sass Syntax@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。

¥Returns a copy of $selector with all instances of $original replaced by $replacement.

这使用 @extend 规则的智能统一来确保 $replacement 无缝集成到 $selector 中。如果 $selector 不包含 $original，则按原样返回。

¥This uses the @extend rule’s intelligent unification to make sure $replacement is seamlessly integrated into $selector. If $selector doesn’t contain $original, returns it as-is.

$selector、$original 和 $replacement 选择器可以包含占位符选择器，但不能包含父选择器。

¥The $selector, $original, and $replacement selectors may contain placeholder selectors, but not parent selectors.

另见 selector.extend()。

¥See also selector.extend().

  SCSS

  Sass

      
      Playground
    SCSS Syntax@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

      
      Playground
    Sass Syntax@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 都匹配的元素的选择器。

¥Returns a selector that matches only elements matched by both $selector1 and $selector2.

如果 $selector1 和 $selector2 不匹配任何相同元素，或者没有选择器可以表达它们的重叠，则返回 null。

¥Returns null if $selector1 and $selector2 don’t match any of the same elements, or if there’s no selector that can express their overlap.

与 @extend 规则生成的选择器一样，如果 $selector1 和 $selector2 都是复杂选择器，则返回的选择器不能保证与 $selector1 和 $selector2 匹配的所有元素匹配。

¥Like selectors generated by the @extend rule, the returned selector isn’t guaranteed to match all the elements matched by both $selector1 and $selector2 if they’re both complex selectors.

  SCSS

  Sass

      
      Playground
    SCSS Syntax@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

      
      Playground
    Sass Syntax@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 中的简单选择器列表。

¥Returns a list of simple selectors in $selector.

$selector 必须是包含复合选择器的单个字符串。这意味着它不能包含组合符（包括空格）或逗号。

¥The $selector must be a single string that contains a compound selector. This means it may not contain combinators (including spaces) or commas.

返回的列表以逗号分隔，简单选择器是不带引号的字符串。

¥The returned list is comma-separated, and the simple selectors are unquoted strings.

  SCSS

  Sass

      Playground
    SCSS Syntax@use "sass:selector";

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

      Playground
    Sass Syntax@use "sass:selector"

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