Skip to main content

Node.js API

Stylelint 模块包含提供 Node.js API 的 lint() 函数。

¥The Stylelint module includes a lint() function that provides the Node.js API.

const result = await stylelint.lint(options);

选项​

¥Options

除了 标准选项 之外，Node API 还接受：

¥In addition to the standard options, the Node API accepts:

config​

一个 配置对象。

¥A configuration object.

如果你使用此选项，Stylelint 不会费心寻找配置文件（例如 stylelint.config.js）。

¥Stylelint does not bother looking for a configuration file (e.g. stylelint.config.js) if you use this option.

code​

一个要掉毛的字符串。

¥A string to lint.

cwd​

Stylelint 将从中查找文件的目录。默认为 process.cwd() 返回的当前工作目录。

¥The directory from which Stylelint will look for files. Defaults to the current working directory returned by process.cwd().

files​

一个文件 glob，或者 文件全局 的数组。

¥A file glob, or array of file globs.

相对 glob 被认为是相对于 globbyOptions.cwd 的。

¥Relative globs are considered relative to globbyOptions.cwd.

虽然 files 和 code 都是 "optional"，但你必须有一个，不能同时拥有。

¥Though both files and code are "optional", you must have one and cannot have both.

globbyOptions​

通过 files 传递的选项。

¥The options that are passed with files.

例如，你可以设置在通配路径时使用的特定 cwd。files 中的相对 glob 被认为是相对于该路径的。默认情况下，globbyOptions.cwd 将由 cwd 设置。

¥For example, you can set a specific cwd to use when globbing paths. Relative globs in files are considered relative to this path. By default, globbyOptions.cwd will be set by cwd.

更详细的使用方法请参见 全球指南。

¥For more detail usage, see Globby Guide.

返回的 promise​

¥The returned promise

stylelint.lint() 返回一个 Promise，该 Promise 解析为包含以下属性的对象：

¥stylelint.lint() returns a Promise that resolves with an object containing the following properties:

code​

如果 fix 选项设置为 true 并且提供了 code 选项，则包含自动修复代码的字符串。否则为 undefined。

¥A string that contains the autofixed code, if the fix option is set to true and the code option is provided. Otherwise, it is undefined.

cwd​

用作 linting 操作的工作目录的目录。

¥The directory used as the working directory for the linting operation.

errored​

布尔值。如果是 true，则至少有一条具有 "error" 级严重性的规则记录了问题。

¥Boolean. If true, at least one rule with an "error"-level severity registered a problem.

output​

[!WARNING] 此属性已弃用，将在下一个主要版本中删除。请改用 report 或 code。参见 迁移指南。

¥[!WARNING] This property is deprecated and will be removed in the next major version. Use report or code instead. See the migration guide.

包含以下任一内容的字符串：

¥A string that contains either the:

  • 格式化问题（使用默认格式化程序或你通过的任何一个）

    ¥formatted problems (using the default formatter or whichever you passed)

  • 或自动修复代码（如果 fix 选项设置为 true）

    ¥or the autofixed code, if the fix option is set to true

postcssResults​

包含所有累积的 PostCSS LazyResults 的数组。

¥An array containing all the accumulated PostCSS LazyResults.

report​

包含格式化问题的字符串（使用默认格式化程序或你传递的任何格式化程序）。

¥A string that contains the formatted problems (using the default formatter or whichever you passed).

results​

包含所有 Stylelint 结果对象（格式化程序使用的对象）的数组。

¥An array containing all the Stylelint result objects (the objects that formatters consume).

maxWarningsExceeded​

包含最大警告数量和发现数量的对象，例如 { maxWarnings: 0, foundWarnings: 12 }。

¥An object containing the maximum number of warnings and the amount found, e.g. { maxWarnings: 0, foundWarnings: 12 }.

结果对象​

¥Result object

{
  "source": "path/to/file.css", // The filepath or PostCSS identifier like <input css 1>
  "errored": true, // This is `true` if at least one rule with an "error"-level severity triggered a warning
  "warnings": [
    // Array of rule problem warning objects, each like the following ...
    {
      "line": 3,
      "column": 12,
      "endLine": 4,
      "endColumn": 15,
      "rule": "block-no-empty",
      "severity": "error",
      "text": "You should not have an empty block (block-no-empty)"
    }
  ],
  "deprecations": [
    // Array of deprecation warning objects, each like the following ...
    {
      "text": "Feature X has been deprecated and will be removed in the next major version.",
      "reference": "https://stylelint.nodejs.cn/docs/feature-x.md"
    }
  ],
  "invalidOptionWarnings": [
    // Array of invalid option warning objects, each like the following ...
    {
      "text": "Invalid option X for rule Y"
    }
  ],
  "ignored": false // This is `true` if the file's path matches a provided ignore pattern
}

编辑信息​

¥Edit info

启用 computeEditInfo 选项 后，警告可能包含 fix 属性，该属性提供有关建议修复的信息：

¥When the computeEditInfo option is enabled, a warning may include a fix property that provides information about suggested fixes:

  • range([number, number]) - 要删除的源代码文本中的一对基于 0 的索引

    ¥range ([number, number]) - the pair of 0-based indices in source code text to remove

  • text(string) - 要添加的文本

    ¥text (string) - the text to add

例如，要将 a { opacity: 10%; } 更改为 a { opacity: 0.1; }，EditInfo 可能如下所示：

¥For example, to change a { opacity: 10%; } to a { opacity: 0.1; }, the EditInfo might look like:

{
  // "line", "column", "rule", ...
  "fix": {
    "range": [13, 16], // Indices of "10%"
    "text": "0.1" // Replacement text
  }
}

要应用此编辑，你需要：

¥To apply this edit, you would:

const sourceCodeText = "a { opacity: 10%; }";
const result =
  sourceCodeText.slice(0, edit.range[0]) + // "a { opacity: "
  edit.text + // "0.1"
  sourceCodeText.slice(edit.range[1]); // "; }"
//=> "a { opacity: 0.1; }"

源代码中的特定区域只会记录一个 EditInfo。如果多个报告范围重叠，则只有第一个将包含 EditInfo。

¥Only a single EditInfo will be recorded for a specific region in source code. If multiple report ranges overlap, only the first will contain EditInfo.

语法错误​

¥Syntax errors

当你的 CSS 包含语法错误时，stylelint.lint() 不会拒绝 Promise。它使用包含语法错误信息的对象（参见 返回的 promise）进行解析。

¥stylelint.lint() does not reject the Promise when your CSS contains syntax errors. It resolves with an object (see the returned promise) that contains information about the syntax error.

使用示例​

¥Usage examples

示例 A​

¥Example A

由于 config 不包含 extends 或 plugins 的相对路径，因此你不必使用 configBasedir：

¥As config contains no relative paths for extends or plugins, you do not have to use configBasedir:

try {
  const result = await stylelint.lint({
    config: { rules: "color-no-invalid-hex" },
    files: "all/my/stylesheets/*.css"
  });
  // do things with result.report, result.errored, and result.results
} catch (err) {
  // do things with err e.g.
  console.error(err.stack);
}

示例 B​

¥Example B

如果 myConfig 确实包含 extends 或 plugins 的相对路径，则必须使用 configBasedir：

¥If myConfig does contain relative paths for extends or plugins, you do have to use configBasedir:

const result = await stylelint.lint({
  config: myConfig,
  configBasedir: url.fileURLToPath(new URL("configs", import.meta.url)),
  files: "all/my/stylesheets/*.css"
});

示例 C​

¥Example C

使用字符串代码代替文件 glob，并使用详细格式化程序代替默认 JSON：

¥Using a string code instead of a file glob, and the verbose formatter instead of the default JSON:

const result = await stylelint.lint({
  code: "a { color: pink; }",
  config: myConfig,
  formatter: "verbose"
});

// do things with result.report

该报告将作为返回对象中 report 属性的值提供。

¥The report will be available as the value of the report property in the returned object.

示例 D​

¥Example D

使用你自己的自定义格式化程序函数：

¥Using your own custom formatter function:

const result = await stylelint.lint({
  config: myConfig,
  files: "all/my/stylesheets/*.css",
  formatter: (results) => {
    /* .. */
  }
});

示例 E​

¥Example E

使用自定义语法：

¥Using a custom syntax:

const result = await stylelint.lint({
  config: myConfig,
  files: "all/my/stylesheets/*.css",
  customSyntax: {
    parse(css, opts) {
      /* .. */
    },
    stringify(node, builder) {
      /* .. */
    }
  }
});
note

customSyntax 选项也接受字符串。有关详细信息，请参阅选项文档。

¥[!NOTE] The customSyntax option also accepts a string. Refer to the options documentation for details.

示例 F​

¥Example F

使用字符串代码和 fix 选项：

¥Using a string code and the fix option:

const result = await stylelint.lint({
  code: "a { color: pink; }",
  config: { rules: { "hue-degree-notation": "angle" } },
  fix: true
});

// do things with result.code

自动修复的代码将作为返回对象中 code 属性的值提供。

¥The autofixed code will be available as the value of the code property in the returned object.

解析文件的有效配置​

¥Resolving the effective config for a file

如果你想找出文件将使用什么确切配置而不实际检查它，你可以使用 resolveConfig() 函数。给定一个文件路径，它将返回一个用有效配置对象解析的 Promise：

¥If you want to find out what exact configuration will be used for a file without actually linting it, you can use the resolveConfig() function. Given a file path, it will return a Promise that resolves with the effective configuration object:

const config = await stylelint.resolveConfig(filePath);

// config => {
//   rules: {
//     'color-no-invalid-hex': true
//   },
//   extends: [
//     'stylelint-config-standard',
//     'stylelint-config-css-modules'
//   ],
//   plugins: [
//     'stylelint-scss'
//   ],
//   …
// }

如果找不到文件的配置，resolveConfig() 将返回解析为 undefined 的 Promise。

¥If a configuration cannot be found for a file, resolveConfig() will return a Promise that resolves to undefined.

你还可以传递 通常传递给 lint() 的选项 的以下子集：

¥You can also pass the following subset of the options that you would normally pass to lint():

  • cwd

  • config

  • configBasedir

  • customSyntax