自定义格式化器

自定义格式化器使您可以以最适合您需求的格式显示代码检查结果，无论是特定文件格式、特定显示样式，还是针对特定工具优化的格式。

ESLint 也有内置格式化器，您可以使用它们。

您可以直接将自定义格式化器包含在您的项目中，或创建 npm 包以单独分发它们。

创建自定义格式化器

每个格式化器都是一个函数，它接收 results 对象和 context 作为参数，并返回一个字符串。例如，以下是如何实现内置的 JSON 格式化器的方法

//my-awesome-formatter.js
module.exports = function(results, context) {
    return JSON.stringify(results, null, 2);
};
1
2
3
4

格式化器也可以是异步函数（从 ESLint v8.4.0 开始），以下显示了一个简单的示例

//my-awesome-formatter.js
module.exports = async function(results) {
    const formatted = await asyncTask();
    return formatted;
};
1
2
3
4
5

要使用此格式化器运行 ESLint，您可以使用 -f（或 --format）命令行标志。您必须用句点 (.) 开头本地定义的自定义格式化器的路径，例如 ./my-awesome-formatter.js 或 ../formatters/my-awesome-formatter.js。

eslint -f ./my-awesome-formatter.js src/
1

本节的其余部分包含有关如何使用自定义格式化器函数的参考信息。

results 参数

传递给格式化器的 results 对象是一个 result 对象的数组，其中包含单个文件的代码检查结果。以下是一个示例输出

[
    {
        filePath: "/path/to/a/file.js",
        messages: [
            {
                ruleId: "curly",
                severity: 2,
                message: "Expected { after 'if' condition.",
                line: 2,
                column: 1,
                nodeType: "IfStatement"
            },
            {
                ruleId: "no-process-exit",
                severity: 2,
                message: "Don't use process.exit(); throw an error instead.",
                line: 3,
                column: 1,
                nodeType: "CallExpression"
            }
        ],
        errorCount: 2,
        warningCount: 0,
        fixableErrorCount: 0,
        fixableWarningCount: 0,
        source:
            "var err = doStuff();\nif (err) console.log('failed tests: ' + err);\nprocess.exit(1);\n"
    },
    {
        filePath: "/path/to/Gruntfile.js",
        messages: [],
        errorCount: 0,
        warningCount: 0,
        fixableErrorCount: 0,
        fixableWarningCount: 0
    }
]
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

result 对象

results 数组中的每个对象都是一个 result 对象。每个 result 对象包含已检查文件的路径以及遇到的代码检查问题的信息。以下是每个 result 对象上可用的属性

filePath：已检查文件的绝对路径。
messages：一个 message 对象的数组。有关消息的更多信息，请参见下文。
errorCount：给定文件的错误数量。
warningCount：给定文件的警告数量。
stats：可选的 stats 对象，它只在使用 stats 选项时存在。
source：给定文件的源代码。如果此文件没有错误/警告，或者如果存在 output 属性，则此属性将被省略。
output：给定文件的源代码，其中应用了尽可能多的修复。如果无法修复，则此属性将被省略。

message 对象

每个 message 对象都包含有关由某些源代码触发的 ESLint 规则的信息。每个 message 对象上可用的属性是

ruleId：生成错误或警告的规则的 ID。如果错误或警告不是由规则生成的（例如，如果它是一个解析错误），则为 null。
severity：故障的严重程度，1 表示警告，2 表示错误。
message：错误的人类可读描述。
line：问题所在的行。
column：问题所在的列。
nodeType：(已弃用：此属性将在 ESLint 的未来版本中删除。) AST 中节点的类型，或者如果问题与特定 AST 节点无关，则为 null。

context 参数

格式化器函数接收 context 对象作为其第二个参数。该对象具有以下属性

cwd：当前工作目录。此值来自 ESLint 类的 cwd 构造函数选项。
maxWarningsExceeded（可选）：如果设置了 --max-warnings 并且警告数量超过了限制，则此属性的值是一个包含两个属性的对象
- maxWarnings：--max-warnings 选项的值
- foundWarnings：lint 警告的数量
rulesMeta：规则的 meta 属性值。有关规则的更多信息，请参见自定义规则页面。

例如，以下是如果运行了 no-extra-semi 规则，该对象的外观

{
    cwd: "/path/to/cwd",
    maxWarningsExceeded: {
        maxWarnings: 5,
        foundWarnings: 6
    },
    rulesMeta: {
        "no-extra-semi": {
            type: "suggestion",
            docs: {
                description: "disallow unnecessary semicolons",
                recommended: true,
                url: "https://eslint.org.cn/docs/rules/no-extra-semi"
            },
            fixable: "code",
            schema: [],
            messages: {
                unexpected: "Unnecessary semicolon."
            }
        }
    },
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

注意：如果代码检查是由已弃用的 CLIEngine 类执行的，则 context 参数可能是一个不同的值，因为它取决于 API 用户。如果您想支持旧版环境，请检查 context 参数是否是预期的值。

将参数传递给格式化器

虽然格式化器函数除了结果对象和上下文之外没有接收参数，但可以使用下面描述的方法将其他数据传递到自定义格式化器中。

使用环境变量

自定义格式化器可以访问环境变量，因此可以根据环境变量数据更改其行为。

以下是一个使用 FORMATTER_SKIP_WARNINGS 环境变量来确定是否在结果中显示警告的示例

module.exports = function(results) {
    var skipWarnings = process.env.FORMATTER_SKIP_WARNINGS === "true";

    var results = results || [];
    var summary = results.reduce(
        function(seq, current) {
            current.messages.forEach(function(msg) {
                var logMessage = {
                    filePath: current.filePath,
                    ruleId: msg.ruleId,
                    message: msg.message,
                    line: msg.line,
                    column: msg.column
                };

                if (msg.severity === 1) {
                    logMessage.type = "warning";
                    seq.warnings.push(logMessage);
                }
                if (msg.severity === 2) {
                    logMessage.type = "error";
                    seq.errors.push(logMessage);
                }
            });
            return seq;
        },
        {
            errors: [],
            warnings: []
        }
    );

    if (summary.errors.length > 0 || summary.warnings.length > 0) {
        var warnings = !skipWarnings ? summary.warnings : []; // skip the warnings in that case

        var lines = summary.errors
            .concat(warnings)
            .map(function(msg) {
                return (
                    "\n" +
                    msg.type +
                    " " +
                    msg.ruleId +
                    "\n  " +
                    msg.filePath +
                    ":" +
                    msg.line +
                    ":" +
                    msg.column
                );
            })
            .join("\n");

        return lines + "\n";
    }
};
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56

您可以使用此自定义格式化器和设置的环境变量来运行 ESLint，如下所示

FORMATTER_SKIP_WARNINGS=true eslint -f ./my-awesome-formatter.js src/
1

输出将是

error space-infix-ops
  src/configs/bundler.js:6:8

error semi
  src/configs/bundler.js:6:10
1
2
3
4
5

复杂的参数传递

如果您发现自定义格式化器模式没有提供足够的选项来满足您希望格式化 ESLint 结果的方式，最好的选择是使用 ESLint 的内置 JSON 格式化器并将输出传递到第二个程序。例如

eslint -f json src/ | your-program-that-reads-JSON --option
1

在此示例中，your-program-that-reads-json 程序可以接受 ESLint 结果的原始 JSON，并在输出其自身的结果格式之前对其进行处理。您可以根据需要向该程序传递任意数量的命令行参数以自定义输出。

终端格式化

像 iTerm2 或 Guake 这样的现代终端期望特定的结果格式才能在单击文件名时自动打开它们。大多数终端都支持此格式以实现该目的

file:line:column
1

打包自定义格式化器

自定义格式化器可以通过 npm 包分发。为此，请创建一个 npm 包，其名称格式为 eslint-formatter-*，其中 * 是您的格式化器的名称（例如 eslint-formatter-awesome）。然后，项目应该安装该包，并使用 -f（或 --format）标志使用自定义格式化器，如下所示

eslint -f awesome src/
1

由于 ESLint 知道在指定的格式化器没有以句点开头时查找以 eslint-formatter- 开头的包，因此您在使用打包的自定义格式化器时无需键入 eslint-formatter-。

自定义格式化器 package.json 的提示

必须将 main 入口点设置为实现自定义格式化器的 JavaScript 文件。
添加这些 keywords 以帮助用户找到您的格式化器
- "eslint"
- "eslint-formatter"
- "eslintformatter"

查看 npm 上的所有自定义格式化器。

示例

摘要格式化器

一个只报告错误和警告总数的格式化器将如下所示

module.exports = function(results, context) {
    // accumulate the errors and warnings
    var summary = results.reduce(
        function(seq, current) {
            seq.errors += current.errorCount;
            seq.warnings += current.warningCount;
            return seq;
        },
        { errors: 0, warnings: 0 }
    );

    if (summary.errors > 0 || summary.warnings > 0) {
        return (
            "Errors: " +
            summary.errors +
            ", Warnings: " +
            summary.warnings +
            "\n"
        );
    }

    return "";
};
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

使用上述摘要格式化器运行 eslint

eslint -f ./my-awesome-formatter.js src/
1

将产生以下输出

Errors: 2, Warnings: 4
1

详细格式化器

一个更复杂的报告可能如下所示

module.exports = function(results, context) {
    var results = results || [];

    var summary = results.reduce(
        function(seq, current) {
            current.messages.forEach(function(msg) {
                var logMessage = {
                    filePath: current.filePath,
                    ruleId: msg.ruleId,
                    ruleUrl: context.rulesMeta[msg.ruleId].docs.url,
                    message: msg.message,
                    line: msg.line,
                    column: msg.column
                };

                if (msg.severity === 1) {
                    logMessage.type = "warning";
                    seq.warnings.push(logMessage);
                }
                if (msg.severity === 2) {
                    logMessage.type = "error";
                    seq.errors.push(logMessage);
                }
            });
            return seq;
        },
        {
            errors: [],
            warnings: []
        }
    );

    if (summary.errors.length > 0 || summary.warnings.length > 0) {
        var lines = summary.errors
            .concat(summary.warnings)
            .map(function(msg) {
                return (
                    "\n" +
                    msg.type +
                    " " +
                    msg.ruleId + (msg.ruleUrl ? " (" + msg.ruleUrl + ")" : "") +
                    "\n  " +
                    msg.filePath +
                    ":" +
                    msg.line +
                    ":" +
                    msg.column
                );
            })
            .join("\n");

        return lines + "\n";
    }
};
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54

当您使用此自定义格式化器运行 ESLint 时

eslint -f ./my-awesome-formatter.js src/
1

输出是

error space-infix-ops (https://eslint.org.cn/docs/rules/space-infix-ops)
  src/configs/bundler.js:6:8
error semi (https://eslint.org.cn/docs/rules/semi)
  src/configs/bundler.js:6:10
warning no-unused-vars (https://eslint.org.cn/docs/rules/no-unused-vars)
  src/configs/bundler.js:5:6
warning no-unused-vars (https://eslint.org.cn/docs/rules/no-unused-vars)
  src/configs/bundler.js:6:6
warning no-shadow (https://eslint.org.cn/docs/rules/no-shadow)
  src/configs/bundler.js:65:32
warning no-unused-vars (https://eslint.org.cn/docs/rules/no-unused-vars)
  src/configs/clean.js:3:6
1
2
3
4
5
6
7
8
9
10
11
12

编辑此页面