Skip to main content

迁移到 15.0.0

¥Migrating to 15.0.0

此版本包含重大或重大更改。

¥This release contains significant or breaking changes.

重大变化​

¥Significant changes

两个重大变化可能会影响你：

¥Two significant changes may affect you:

  • 已弃用的风格规则

    ¥deprecated stylistic rules

  • 添加了 declaration-property-value-no-unknown 规则

    ¥added the declaration-property-value-no-unknown rule

已弃用的风格规则​

¥Deprecated stylistic rules

我们已弃用 76 条强制执行风格约定的规则：

¥We've deprecated 76 of the rules that enforce stylistic conventions:

  • at-rule-name-case

  • at-rule-name-newline-after

  • at-rule-name-space-after

  • at-rule-semicolon-newline-after

  • at-rule-semicolon-space-before

  • block-closing-brace-empty-line-before

  • block-closing-brace-newline-after

  • block-closing-brace-newline-before

  • block-closing-brace-space-after

  • block-closing-brace-space-before

  • block-opening-brace-newline-after

  • block-opening-brace-newline-before

  • block-opening-brace-space-after

  • block-opening-brace-space-before

  • color-hex-case

  • declaration-bang-space-after

  • declaration-bang-space-before

  • declaration-block-semicolon-newline-after

  • declaration-block-semicolon-newline-before

  • declaration-block-semicolon-space-after

  • declaration-block-semicolon-space-before

  • declaration-block-trailing-semicolon

  • declaration-colon-newline-after

  • declaration-colon-space-after

  • declaration-colon-space-before

  • function-comma-newline-after

  • function-comma-newline-before

  • function-comma-space-after

  • function-comma-space-before

  • function-max-empty-lines

  • function-parentheses-newline-inside

  • function-parentheses-space-inside

  • function-whitespace-after

  • indentation

  • linebreaks

  • max-empty-lines

  • max-line-length

  • media-feature-colon-space-after

  • media-feature-colon-space-before

  • media-feature-name-case

  • media-feature-parentheses-space-inside

  • media-feature-range-operator-space-after

  • media-feature-range-operator-space-before

  • media-query-list-comma-newline-after

  • media-query-list-comma-newline-before

  • media-query-list-comma-space-after

  • media-query-list-comma-space-before

  • no-empty-first-line

  • no-eol-whitespace

  • no-extra-semicolons

  • no-missing-end-of-source-newline

  • number-leading-zero

  • number-no-trailing-zeros

  • property-case

  • selector-attribute-brackets-space-inside

  • selector-attribute-operator-space-after

  • selector-attribute-operator-space-before

  • selector-combinator-space-after

  • selector-combinator-space-before

  • selector-descendant-combinator-no-non-space

  • selector-list-comma-newline-after

  • selector-list-comma-newline-before

  • selector-list-comma-space-after

  • selector-list-comma-space-before

  • selector-max-empty-lines

  • selector-pseudo-class-case

  • selector-pseudo-class-parentheses-space-inside

  • selector-pseudo-element-case

  • string-quotes

  • unicode-bom

  • unit-case

  • value-list-comma-newline-after

  • value-list-comma-newline-before

  • value-list-comma-space-after

  • value-list-comma-space-before

  • value-list-max-empty-lines

当我们创建这些规则时，美化打印器（如 Prettier）还不存在。他们现在提供了一种更好的方法来一致地格式化代码，尤其是空格。代码检查器和美化打印器是互补的工具，它们一起工作可以帮助你编写一致且无错误的代码。

¥When we created these rules, pretty printers (like Prettier) didn't exist. They now offer a better way to consistently format code, especially whitespace. Linters and pretty printers are complementary tools that work together to help you write consistent and error-free code.

通过弃用这些规则，我们可以：

¥By deprecating these rules, we can:

  • 专注于编写和维护有助于你 避免错误 和 强制执行（非文体）惯例 的规则，这两者都是 Stylelint 所独有的

    ¥focus on writing and maintaining rules that help you avoid errors and enforce (non-stylistic) conventions, both of which are unique to Stylelint

  • 使我们的代码库现代化，例如 迁移到 ESM，以便我们可以更新依赖并确保 Stylelint 的安全

    ¥modernize our codebase, e.g. move to ESM so that we can update our dependencies and keep Stylelint secure for you

已弃用的规则在此版本中仍然有效（带有弃用警告）。为了准备下一个主要版本，当我们从 Stylelint 中删除规则时，我们建议：

¥The deprecated rules will still work in this release (with a deprecation warning). In preparation for the next major release, when we'll remove the rules from Stylelint, we suggest:

  • 如果你还没有扩展配置对象中的 标准配置

    ¥extending the standard config in your configuration object, if you don't already

  • 从配置对象中删除已弃用的规则

    ¥removing the deprecated rules from your configuration object

你可以使用 extend 和 标准配置：

¥You can extend the standard config using:

{
+ "extends": ["stylelint-config-standard"],
  "rules": { .. }
}

此外，你可能不再需要扩展 Prettier 的 Stylelint 配置，因为不应存在冲突的规则：

¥Additionally, you may no longer need to extend Prettier's Stylelint config as there should be no conflicting rules:

{
- "extends": ["stylelint-config-prettier"],
  "rules": { .. }
}

我们已从最新版本的 标准配置 中删除了已弃用的规则。它仍然可以通过打开许多 执行公约的其他规则 来帮助你编写一致的 CSS，例如 大部分 *-notation、*-pattern 和 *-quotes 规则。

¥We've removed the deprecated rules from the latest version of the standard config. It still helps you write consistent CSS by turning on many of the other rules that enforce conventions, e.g. most of the *-notation, *-pattern and *-quotes rules.

还有许多其他规则我们没有在 标准配置 中启用，你可以在 新指南 中了解有关使用它们根据你的具体需求自定义 Stylelint 的更多信息。

¥There are lots of other rules we don't turn on in the standard config and you can learn more about using them to customize Stylelint to your exact needs in our new guide.

或者，你可以继续使用已迁移弃用规则的社区插件 @stylistic/stylelint-plugin 来强制使用 Stylelint 实现风格一致性。

¥Alternatively, you can continue to enforce stylistic consistency with Stylelint by using the community plugin @stylistic/stylelint-plugin that has migrated the deprecated rules.

你可以使用 quietDeprecationWarnings 选项来消除弃用警告。

¥You can use the quietDeprecationWarnings option to silence the deprecation warnings.

添加了 declaration-property-value-no-unknown 规则​

¥Added declaration-property-value-no-unknown rule

我们添加了 declaration-property-value-no-unknown 规则。它将标记 CSS 规范中未知的属性-值对，例如：

¥We added the declaration-property-value-no-unknown rule. It will flag property-value pairs that are unknown in the CSS specifications, for example:

a {
  top: red;
}

top 属性接受 <length>、<percentage> 或 auto 关键字。该规则会将 red 标记为 <color>。

¥The top property accepts either a <length>, <percentage> or the auto keyword. The rule will flag red as it's a <color>.

你们中的许多人都请求了这条规则，我们计划添加更多类似的规则来帮助你在 CSS 中实现 避免错误。

¥Many of you have requested this rule, and we plan to add more like it to help you avoid errors in your CSS.

要在配置对象中打开它：

¥To turn it on in your configuration object:

{
  "extends": ["stylelint-config-standard"],
  "rules": {
+   "declaration-property-value-no-unknown": true
    ..
   }
}

该规则使用了 CSS 树 及其 语法词典 的 600 多个属性、350 多个类型和 100 多个函数。你可以通过更新 mdn-data 或 CSSTree 的补丁文件 来帮助识别和填补其字典中的任何空白。

¥The rule uses CSSTree and its syntax dictionary of 600+ properties, 350+ types and 100+ functions. You can help identify and plug any gaps in its dictionary by either updating mdn-data or CSSTree's patch file.

如果你使用 CSS 规范中未包含的值，则可以使用规则的辅助选项来使规则更加宽松。你可以：

¥If you use values that aren't in the CSS specifications, you can use the rule's secondary options to make the rule more permissive. You can either:

  • 完全忽略属性或值

    ¥ignore properties or values outright

  • 扩展属性和值语法

    ¥extend the properties and values syntaxes

后者确保只允许特定的例外情况。

¥The latter ensures only specific exceptions are allowed.

如果你当前使用 stylelint-csstree-validator 插件，则可以通过限制插件仅检查 at 规则名称和前奏来继续与新规则一起使用它。

¥If you currently use the stylelint-csstree-validator plugin, you can continue to use it alongside the new rule by limiting the plugin to check only at-rule names and preludes.

{
  "rules": {
    "csstree/validator": [true, {
+      "ignoreProperties": ["/.+/"]
    }]
  }
}

重大变化​

¥Breaking changes

三个重大变化也可能会影响你：

¥Three breaking changes may also affect you:

  • 删除了 processors 配置属性

    ¥removed processors configuration property

  • 删除了对 Node.js 12 的支持

    ¥removed support for Node.js 12

  • 改变了 overrides.extends 的行为

    ¥changed overrides.extends behavior

删除了 processors 配置属性​

¥Removed processors configuration property

处理器是我们支持 CSS 容器的第一次尝试，例如 Markdown、HTML 和 CSS-in-JS。后来我们推出了 自定义语法 来修复处理器的一些缺点，例如 与 --fix 选项 不兼容。

¥Processors were our first attempt to support containers of CSS, e.g. Markdown, HTML and CSS-in-JS. We later introduced custom syntaxes to fix some of the shortcomings of processors, e.g. incompatibility with the --fix option.

我们还弃用了 postcss-css-in-js 自定义语法。不可能维护一个试图支持每个 CSS-in-JS 库和语法的单一自定义语法，因为它们太多了，而且每个库和语法都有变化。

¥We've also deprecated the postcss-css-in-js custom syntax. It was not possible to maintain a monolithic custom syntax that attempted to support every CSS-in-JS library and syntax, as there are so many of them and each with variations in syntax.

你应该从配置对象中删除 processors 属性，并使用特定于库或特定于语法（例如模板字面量）的 自定义语法 来代替。

¥You should remove the processors property from your configuration object and use a library-specific or syntax-specific (e.g. template literals) custom syntax instead.

例如，如果你使用 styled-components：

¥For example, if you use styled-components:

{
- "processors": ["stylelint-processor-styled-components"],
+ "customSyntax": "postcss-styled-syntax",
  "rules": { .. }
}

其他自定义语法包括：

¥Other custom syntaxes include:

你可以在 很棒的 Stylelint 中找到它们的完整列表。

¥You'll find a complete list of them in Awesome Stylelint.

如果你创建新的自定义语法，请 打开拉取请求 更新 很棒的 Stylelint，以便其他人可以找到它。例如，Stitches 和 vanilla-extract 需要语法，它们是基于对象的 CSS-in-JS 库。

¥If you create a new custom syntax, please open a pull request to update Awesome Stylelint so that others can find it. For example, Stitches and vanilla-extract need syntaxes, which are object-based CSS-in-JS libraries.

删除了对 Node.js 12 的支持​

¥Removed support for Node.js 12

Node.js 12 已终止生命周期。我们已经删除了对它的支持，以便我们可以更新一些依赖。你应该使用以下或更高版本的 Node.js：

¥Node.js 12 has reached end-of-life. We've removed support for it so that we could update some of our dependencies. You should use the following or higher versions of Node.js:

  • 14.13.1

  • 16.0.0

  • 18.0.0

改变了 overrides.extends 行为​

¥Changed overrides.extends behavior

为了与 overrides.plugins 保持一致，我们将 overrides.extends 的行为更改为合并而不是替换。

¥To be consistent with the overrides.plugins, we've changed the behaviour of overrides.extends to merge rather than replace.

如果你想保留以前的行为，你应该将配置更改为：

¥If you would like to keep the previous behavior, you should change your config to:

{
- "extends": ["config-a"],
  "overrides": [
    {
      "files": ["*.module.css"],
      "extends": ["config-b"]
    },
+   {
+     "files": ["*.css"],
+     "extends": ["config-a"]
+   }
  ]
}