Lzh on GitHub

@mixin 和 @include

混合宏允许你定义可以在整个样式表中重复使用的样式。它们使得避免使用 .float-left 等非语义类，以及在库中分发样式集合变得容易。

混合宏允许你定义可以在整个样式表中重复使用的样式。它们使得避免使用 .float-left 等非语义类，以及在库中分发样式集合变得容易。

混合宏使用 @mixin at-rule 定义，其写法为 @mixin <name> { ... } 或 @mixin name(<arguments...>) { ... }。混合宏的名称可以是任何不以 -- 开头的 Sass 标识符，并且它可以包含除顶层语句之外的任何语句。它们可以用来封装可以放入单个样式规则中的样式；它们可以包含自己的样式规则，这些规则可以嵌套在其他规则中，或包含在样式表的顶层；或者它们只是用于修改变量。

混合宏使用 @include at-rule 包含到当前上下文中，其写法为 @include <name> 或 @include <name>(<arguments...>)，其中 <name> 是要包含的混合宏的名称。

@mixin reset-list {
  margin: 0;
  padding: 0;
  list-style: none;
}

@mixin horizontal-list {
  @include reset-list;

  li {
    display: inline-block;
    margin: {
      left: -2px;
      right: 2em;
    }
  }
}

nav ul {
  @include horizontal-list;
}
混合宏名称，像所有 Sass 标识符一样，将连字符和下划线视为相同。这意味着 reset-list 和 reset_list 都指同一个混合宏。这是 Sass 早期的历史遗留问题，当时它只允许在标识符名称中使用下划线。一旦 Sass 添加了对连字符的支持以匹配 CSS 的语法，两者就被设置为等效，以使迁移更容易。

参数

混合宏也可以接受参数，这允许在每次调用时自定义它们的行为。参数在 @mixin 规则中，在混合宏名称后，以圆括号括起来的变量名列表的形式指定。然后，必须使用相同数量的参数（以 SassScript 表达式的形式）来包含混合宏。这些表达式的值在混合宏主体中作为相应的变量可用。

@mixin rtl($property, $ltr-value, $rtl-value) {
  #{$property}: $ltr-value;

  [dir=rtl] & {
    #{$property}: $rtl-value;
  }
}

.sidebar {
  @include rtl(float, left, right);
}
参数列表也可以有逗号结尾！这使得在重构样式表时更容易避免语法错误。

可选参数

通常，混合宏声明的每个参数都必须在包含该混合宏时传递。但是，你可以通过定义一个默认值来使参数可选，如果该参数未传递，则将使用该默认值。默认值使用与变量声明相同的语法：变量名，后跟一个冒号和一个 SassScript 表达式。这使得定义灵活的混合宏 API 变得容易，它们可以以简单或复杂的方式使用。

@mixin replace-text($image, $x: 50%, $y: 50%) {
  text-indent: -99999em;
  overflow: hidden;
  text-align: left;

  background: {
    image: $image;
    repeat: no-repeat;
    position: $x $y;
  }
}

.mail-icon {
  @include replace-text(url("/images/mail.svg"), 0);
}
默认值可以是任何 SassScript 表达式，它们甚至可以引用较早的参数！

关键字参数

当包含一个混合宏时，除了按其在参数列表中的位置传递参数外，还可以按名称传递参数。这对于具有多个可选参数或具有布尔参数的混合宏特别有用，如果没有名称，它们的含义就不那么明显。关键字参数使用与变量声明和可选参数相同的语法。

@mixin square($size, $radius: 0) {
  width: $size;
  height: $size;

  @if $radius != 0 {
    border-radius: $radius;
  }
}

.avatar {
  @include square(100px, $radius: 4px);
}
因为任何参数都可以按名称传递，所以在重命名混合宏的参数时要小心……它可能会破坏你的用户！将旧名称作为可选参数保留一段时间，并在有人传递它时打印警告，这样他们就知道要迁移到新参数，这会很有帮助。

接受任意参数

有时，让一个混合宏能够接受任意数量的参数会很有用。如果 @mixin 声明中的最后一个参数以 ... 结尾，那么传递给该混合宏的所有额外参数都将作为列表传递给该参数。这个参数被称为参数列表。

@mixin order($height, $selectors...) {
  @for $i from 0 to length($selectors) {
    #{nth($selectors, $i + 1)} {
      position: absolute;
      height: $height;
      margin-top: $i * $height;
    }
  }
}

@include order(150px, "input.name", "input.address", "input.zip");

接受任意关键字参数

参数列表也可以用于接受任意关键字参数。meta.keywords() 函数接受一个参数列表，并返回作为映射传递给混合宏的任何额外关键字，该映射从参数名（不包括 $) 映射到这些参数的值。

@use "sass:meta";

@mixin syntax-colors($args...) {
  @debug meta.keywords($args);
  // (string: #080, comment: #800, variable: #60b)

  @each $name, $color in meta.keywords($args) {
    pre span.stx-#{$name} {
      color: $color;
    }
  }
}

@include syntax-colors(
  $string: #080,
  $comment: #800,
  $variable: #60b,
)
如果你从不将参数列表传递给 meta.keywords() 函数，则该参数列表将不允许额外的关键字参数。这有助于混合宏的调用者确保他们没有意外拼错任何参数名称。

传递任意参数

就像参数列表允许混合宏接受任意位置或关键字参数一样，相同的语法可用于传递位置和关键字参数给混合宏。如果你将一个列表后跟 ... 作为包含的最后一个参数，其元素将被视为额外的位置参数。同样，后跟 ... 的映射将被视为额外的关键字参数。你甚至可以同时传递两者！

$form-selectors: "input.name", "input.address", "input.zip" !default;

@include order(150px, $form-selectors...);
因为参数列表同时跟踪位置参数和关键字参数，所以你可以使用它一次将两者传递给另一个混合宏。这使得为混合宏定义别名变得超级容易！
@mixin btn($args...) {
  @warn "The btn() mixin is deprecated. Include button() instead.";
  @include button($args...);
}

内容块

除了接受参数外，混合宏还可以接受一整个样式块，称为内容块。混合宏可以通过在其主体中包含 @content at-rule 来声明它接受一个内容块。内容块使用大括号传入，就像 Sass 中的任何其他块一样，它被注入到 @content 规则的位置。

@mixin hover {
  &:not([disabled]):hover {
    @content;
  }
}

.button {
  border: 1px solid black;
  @include hover {
    border-width: 2px;
  }
}
一个混合宏可以包含多个 @content at-rule。如果它包含多个，内容块将为每个 @content 分别包含。
内容块是词法作用域的，这意味着它只能看到包含混合宏的作用域中的局部变量。它看不到传递给它的混合宏中定义的任何变量，即使它们是在内容块被调用之前定义的。

向内容块传递参数

一个混合宏可以向其内容块传递参数，其方式与向另一个混合宏传递参数的方式相同，即编写 @content(<arguments...>)。编写内容块的用户可以通过编写 @include <name> using (<arguments...>) 来接受参数。内容块的参数列表就像混合宏的参数列表一样工作，而由 @content 传递给它的参数就像传递给混合宏的参数一样工作。

如果一个混合宏向其内容块传递参数，该内容块必须声明它接受这些参数。这意味着最好只按位置（而不是按名称）传递参数，并且传递更多参数是一个破坏性更改。如果你想灵活地向内容块传递信息，可以考虑向它传递一个包含它可能需要的信息的映射！
@mixin media($types...) {
  @each $type in $types {
    @media #{$type} {
      @content($type);
    }
  }
}

@include media(screen, print) using ($type) {
  h1 {
    font-size: 40px;
    @if $type == print {
      font-family: Calluna;
    }
  }
}

缩进混合宏语法

除了标准的 @mixin 和 @include 之外，缩进语法还有一种特殊的语法来定义和使用混合宏。混合宏使用字符 = 定义，并使用 + 包含。虽然这种语法更简洁，但它也更难一眼看懂，因此鼓励用户避免使用它。

=reset-list
  margin: 0
  padding: 0
  list-style: none

=horizontal-list
  +reset-list

  li
    display: inline-block
    margin:
      left: -2px
      right: 2em

nav ul
  +horizontal-list