重大变化：颜色 JS API

正如 Sass 的颜色函数正在弃用 的某些方面增加了对 CSS 颜色 4 的支持一样，用于操作颜色的 JS API 的某些方面也被弃用了。

¥Just as some aspects of Sass’s color functions are being deprecated with the addition of support for CSS Color 4, some corners of the JS API for manipulating colors are deprecated as well.

color.change() 现在需要 space 进行跨空间更改color.change() 现在需要 space 进行跨空间更改 permalink

¥color.change() now requires a space for cross-space changes

以前，color.change() 方法 只是从 RGB、HSL 或 HWB 空间中获取一组通道名称。只要这些通道没有跨空间混合（例如，同时更改 red 和 hue），Sass 就可以确定哪个空间是预期的。

¥Previously, the color.change() method just took a set of channel names from the RGB, HSL, or HWB spaces. As long as those channels weren’t mixed across spaces (for example by changing both red and hue at the same time), Sass could figure out which space was intended.

使用 Color 4，仅从通道名称就无法明确区分颜色空间。许多空间都有具有不同范围的 red、green 和 blue 通道；许多空间都有 hue 通道，它们会产生非常不同的色轮。为了解决这种歧义，color.change() 现在采用 space 参数，该参数明确指定要在其中进行转换的颜色空间的名称：

¥With Color 4, color spaces are no longer unambiguous from their channel names alone. Many spaces have red, green, and blue channels with different ranges; many spaces have hue channels which produce very different color wheels. To fix this ambiguity, color.change() now takes a space parameter which explicitly specifies the name of the color space you want to do the transformation in:

const color = new sass.SassColor({red: 0x66, green: 0x33, blue: 0x99});
color.change({hue: 270, space: "okclh"});

如果所讨论的颜色不在 旧颜色空间 中，或者你正在更改仅存在于非传统颜色空间中的通道（如色度），则必须指定颜色空间。如果你要更改颜色自身空间中存在的通道，则始终是可选的，因此 color.change({red: 0.8}) 始终指的是具有 red、green 和 blue 通道的任何颜色的原生红色通道。

¥Specifying the color space is mandatory if the color in question isn’t in a legacy color space or if you’re changing a channel like chroma that only exists in non-legacy color spaces. It’s always optional if you’re changing a channel that exists in the color’s own space, so color.change({red: 0.8}) always refers to the native red channel of any color with red, green, and blue channels.

为了向后兼容，如果你要将旧通道更改为旧颜色，Sass 仍会自动为你转换颜色。但是，此行为已被弃用。为了安全起见，除非你确定颜色已经在要更改其通道的颜色空间中，否则应始终传递 space 参数。

¥For backwards-compatibility, if you’re changing legacy channels for a legacy color, Sass will still automatically convert the color for you. However, this behavior is deprecated. To be safe, you should always pass the space parameter unless you’re sure the color is already in the color space whose channel you want to change.

null 通道值null 通道值 permalink

¥null channel values

CSS Color 4 中的一个主要变化是 "missing" 通道 的新概念。例如，hsl(none 0% 40%) 缺少色调，在大多数情况下被视为 0，但不参与颜色插值，因此具有此颜色的渐变不会在中间出现幻影红色色调。构造颜色时，Sass 将缺失值表示为值 null。

¥One of the major changes in CSS Color 4 is the new concept of "missing" channels. For example, hsl(none 0% 40%) has a missing hue, which is treated as 0 in most cases but doesn’t contribute to color interpolation so that a gradient with this color won’t have a phantom red hue in the middle. When constructing colors, Sass represents missing values as the value null.

在添加对 CSS Color 4 的支持之前，Sass JS API 的 TypeScript 类型禁止在所有相关的地方使用 null。但是，代码本身将 null 与 undefined 相同，我们不想破坏与依赖此行为的任何纯 JavaScript 代码的兼容性。目前，null 值被视为 undefined，并在构造新的 [旧颜色] 或为旧颜色调用 color.change() 时发出弃用警告。无论哪种情况，如果你明确传递 space 参数，你将选择新行为，而 null 将被视为缺失通道。

¥Before adding support for CSS Color 4, the Sass JS API’s TypeScript types forbade the use of null in all places where it was relevant. However, the code itself treated null the same as undefined, and we don’t want to break compatibility with any plain JavaScript code that was relying on this behavior. For now, a null value is treated as undefined and emits a deprecation warning when constructing a new [legacy color] or calling color.change() for a legacy color. In either case, if you pass a space parameter explicitly, you’ll opt into the new behavior and null will be treated as a missing channel.

过渡期过渡期 permalink

¥Transition Period

兼容性:

Dart Sass

since 1.79.0

LibSass

✗

Ruby Sass

✗

首先，我们将针对所有计划更改的这些 API 的使用发出弃用警告。在 Dart Sass 2.0.0 中，重大更改将完全生效，旧行为将不再像以前那样起作用。

¥First, we’ll emit deprecation warnings for all uses of these APIs that are slated to be changed. In Dart Sass 2.0.0, the breaking changes will go into effect fully, and the old behavior will no longer work how it used to.

Can I Silence the Warnings?Can I Silence the Warnings? permalink

Sass provides a powerful suite of options for managing which deprecation warnings you see and when.

Terse and Verbose ModeTerse and Verbose Mode permalink

By default, Sass runs in terse mode, where it will only print each type of deprecation warning five times before it silences additional warnings. This helps ensure that users know when they need to be aware of an upcoming breaking change without creating an overwhelming amount of console noise.

If you run Sass in verbose mode instead, it will print every deprecation warning it encounters. This can be useful for tracking the remaining work to be done when fixing deprecations. You can enable verbose mode using the verbose option in the JavaScript API.

Silencing Deprecations in DependenciesSilencing Deprecations in Dependencies permalink

Sometimes, your dependencies have deprecation warnings that you can’t do anything about. You can silence deprecation warnings from dependencies while still printing them for your app using the quietDeps option in the JavaScript API.

For the purposes of this flag, a "dependency" is any stylesheet that’s not just a series of relative loads from the entrypoint stylesheet. This means anything that comes from a load path, and most stylesheets loaded through custom importers.

Silencing Specific DeprecationsSilencing Specific Deprecations permalink

If you know that one particular deprecation isn’t a problem for you, you can silence warnings for that specific deprecation using the silenceDeprecations option in the JavaScript API.