Skip to main content

ESLint 插件

要点

本页介绍如何使用 typescript-eslint 编写你自己的自定义 ESLint 插件。在编写自定义插件之前，你应该熟悉 ESLint 的插件指南 和 typescript-eslint 自定义规则。

¥This page describes how to write your own custom ESLint plugins using typescript-eslint. You should be familiar with ESLint's plugins guide and typescript-eslint Custom Rules before writing custom plugins.

支持 TypeScript 代码和类型化 linting 的自定义插件看起来与任何其他 ESLint 插件非常相似。按照与 ESLint 的插件指南 > 创建插件 相同的一般步骤设置你的插件。所需的差异在此页面上注明。

¥Custom plugins that support TypeScript code and typed linting look very similar to any other ESLint plugin. Follow the same general steps as ESLint's plugins guide > Creating a plugin to set up your plugin. The required differences are noted on this page.

提示

有关支持类型化 linting 的示例插件，请参阅 eslint-plugin-example-typed-linting。

¥See eslint-plugin-example-typed-linting for an example plugin that supports typed linting.

软件包依赖​

¥Package Dependencies

你的插件应该具有以下 package.json 条目。

¥Your plugin should have the following package.json entries.

对于所有 @typescript-eslint 和 typescript-eslint 包，请将它们保持在相同的 semver 版本。例如，你可以将它们中的每一个设置为 ^8.1.2 或 ^7.12.0 || ^8.0.0。

¥For all @typescript-eslint and typescript-eslint packages, keep them at the same semver versions. As an example, you might set each of them to ^8.1.2 or ^7.12.0 || ^8.0.0.

dependencies​

@typescript-eslint/utils 是 RuleCreator 工厂创建规则 所必需的。

¥@typescript-eslint/utils is required for the RuleCreator factory to create rules.

devDependencies​

强烈建议使用 @typescript-eslint/rule-tester 才能使用 使用我们的 RuleTester 测试规则。

¥@typescript-eslint/rule-tester is strongly recommended to be able to test rules with our RuleTester.

peerDependencies​

包含以下内容以强制执行允许的版本范围，而无需让用户的包管理器安装它们：

¥Include the following to enforce the version range allowed without making users' package managers install them:

  • @typescript-eslint/parser 和任何其他解析器用户都应使用

    ¥@typescript-eslint/parser and any other parsers users are expected to be using

  • eslint

  • typescript

这些都是消费者预计已经使用的软件包。

¥Those are all packages consumers are expected to be using already.

你不需要声明对 typescript-eslint 或 @typescript-eslint/eslint-plugin 的任何依赖。我们的设置指南确保在配置 ESLint 时自动注册解析器。

¥You don't need to declare any dependencies on typescript-eslint or @typescript-eslint/eslint-plugin. Our setup guide ensures that the parser is automatically registered when configuring ESLint.

RuleCreator 用法​

¥RuleCreator Usage

我们建议在插件的 RuleCreator 额外规则文档类型 中至少包含以下三个属性：

¥We recommend including at least the following three properties in your plugin's RuleCreator extra rule docs types:

  • description: string：规则功能的简洁描述

    ¥description: string: a succinct description of what the rule does

  • recommended?: boolean：规则是否存在于插件的共享“recommended”配置中

    ¥recommended?: boolean: whether the rule exists in your plugin's shared "recommended" config

  • requiresTypeChecking?: boolean：规则是否将使用类型信息，用于文档生成器（例如 eslint-doc-generator）

    ¥requiresTypeChecking?: boolean: whether the rule will use type information, for documentation generators such as eslint-doc-generator

例如，来自 eslint-plugin-example-typed-linting 的 utils.ts：

¥For example, from eslint-plugin-example-typed-linting's utils.ts:

import { ESLintUtils } from '@typescript-eslint/utils';

export interface ExamplePluginDocs {
  description: string;
  recommended?: boolean;
  requiresTypeChecking?: boolean;
}

export const createRule = ESLintUtils.RuleCreator<ExamplePluginDocs>(
  name =>
    `https://github.com/your/eslint-plugin-example/tree/main/docs/${name}.md`,
);

类型检查和配置​

¥Type Checking and Configs

大多数 ESLint 插件都会导出“recommended”ESLint 共享配置。许多 ESLint 用户认为启用插件的 recommended 配置足以启用其所有相关规则。

¥Most ESLint plugins export a "recommended" ESLint shared config. Many ESLint users assume enabling a plugin's recommended config is enough to enable all its relevant rules.

但是，与此同时，并非所有用户都希望或能够启用类型化 linting。如果你的插件规则大量使用类型信息，则可能很难在 recommended 配置中启用这些信息。

¥However, at the same time, not all users want to or are able to enabled typed linting. If your plugin's rules heavily use type information, it might be difficult to enable those in a recommended config.

你大致有两个选择：

¥You have roughly two options:

  • 让你的插件的 recommended 配置需要启用类型信息

    ¥Have your plugin's recommended config require enabling type information

  • 有一个单独的配置，名称类似 recommendedTypeChecked

    ¥Have a separate config with a name like recommendedTypeChecked

无论哪种方式，请在你的文档中明确提及采取的策略。

¥Either way, explicitly mention the strategy taken in your docs.

信息

根据 自定义规则 > 条件类型信息，我们建议不要根据类型信息是否可用来更改规则逻辑。

¥Per Custom Rules > Conditional Type Information, we recommend not changing rule logic based on whether type information is available.

提示

有关支持类型化 linting 的示例插件，请参阅 eslint-plugin-example-typed-linting。

¥See eslint-plugin-example-typed-linting for an example plugin that supports typed linting.