Skip to main content

ban-ts-comment

Disallow @ts-<directive> comments or require descriptions after directives.

✅

在 ESLint 配置 中扩展"plugin:@typescript-eslint/recommended" 可启用此规则。

💡

此规则报告的一些问题可以通过编辑器 建议 手动修复。


TypeScript 提供了几个指令注释，可用于改变它处理文件的方式。 使用这些来抑制 TypeScript 编译器错误会降低 TypeScript 的整体效率。 相反，通常最好纠正代码类型，以使指令变得不必要。

英：TypeScript provides several directive comments that can be used to alter how it processes files. Using these to suppress TypeScript compiler errors reduces the effectiveness of TypeScript overall. Instead, it's generally better to correct the types of code, to make directives unnecessary.

TypeScript 支持的指令注释有：

英：The directive comments supported by TypeScript are:

// @ts-expect-error
// @ts-ignore
// @ts-nocheck
// @ts-check

此规则允许你设置要在代码库中允许哪些指令注释。

英：This rule lets you set which directive comments you want to allow in your codebase.

.eslintrc.cjs
module.exports = {
  "rules": {
    "@typescript-eslint/ban-ts-comment": "error"
  }
};
在线运行试试这个规则 ↗

选项​

默认情况下，仅允许使用 @ts-check，因为它会启用而不是抑制错误。

英：By default, only @ts-check is allowed, as it enables rather than suppresses errors.

ts-expect-error、ts-ignore、ts-nocheck、ts-check 指令​

特定指令的 true 值意味着该规则将报告是否发现该指令的任何用法。

英：A value of true for a particular directive means that this rule will report if it finds any usage of said directive.

if (false) {
  // @ts-ignore: Unreachable code error
  console.log('hello');
}
if (false) {
  /*
  @ts-ignore: Unreachable code error
  */
  console.log('hello');
}
Open in Playground

allow-with-description​

特定指令的 'allow-with-description' 值意味着，如果该规则发现指令后面没有说明（在同一行），则该规则将报告。

英：A value of 'allow-with-description' for a particular directive means that this rule will report if it finds a directive that does not have a description following the directive (on the same line).

例如，对于 { 'ts-expect-error': 'allow-with-description' }：

英：For example, with { 'ts-expect-error': 'allow-with-description' }:

if (false) {
  // @ts-expect-error
  console.log('hello');
}
if (false) {
  /* @ts-expect-error */
  console.log('hello');
}
Open in Playground

descriptionFormat​

对于每种指令类型，你可以以正则表达式的形式指定自定义格式。 仅允许与模式匹配的描述。

英：For each directive type, you can specify a custom format in the form of a regular expression. Only description that matches the pattern will be allowed.

例如，对于 { 'ts-expect-error': { descriptionFormat: '^: TS\\d+ because .+ } }：

英：For example, with { 'ts-expect-error': { descriptionFormat: '^: TS\\d+ because .+$' } }:

// @ts-expect-error: the library definition is wrong
const a = doSomething('hello');
Open in Playground

minimumDescriptionLength​

当对指令使用 allow-with-description 选项时，使用 minimumDescriptionLength 设置描述的最小长度。

英：Use minimumDescriptionLength to set a minimum length for descriptions when using the allow-with-description option for a directive.

例如，对于 { 'ts-expect-error': 'allow-with-description', minimumDescriptionLength: 10 }，以下模式是：

英：For example, with { 'ts-expect-error': 'allow-with-description', minimumDescriptionLength: 10 } the following pattern is:

if (false) {
  // @ts-expect-error: TODO
  console.log('hello');
}
Open in Playground

何时不使用它​

如果你的项目或其依赖在构建时没有考虑到强类型安全性，则可能很难始终遵守正确的 TypeScript 语义。 你可以考虑在这些特定情况下使用 ESLint 禁用注释，而不是完全禁用此规则。

英：If your project or its dependencies were not architected with strong type safety in mind, it can be difficult to always adhere to proper TypeScript semantics. You might consider using ESLint disable comments for those specific situations instead of completely disabling this rule.

进一步阅读​

选项​

该规则接受以下选项

type DirectiveConfigSchema =
  | 'allow-with-description'
  | {
      descriptionFormat?: string;
    }
  | boolean;

type Options = [
  {
    'ts-check'?: DirectiveConfigSchema;
    'ts-expect-error'?: DirectiveConfigSchema;
    'ts-ignore'?: DirectiveConfigSchema;
    'ts-nocheck'?: DirectiveConfigSchema;
    minimumDescriptionLength?: number;
  },
];

const defaultOptions: Options = [
  {
    'ts-expect-error': 'allow-with-description',
    'ts-ignore': true,
    'ts-nocheck': true,
    'ts-check': false,
    minimumDescriptionLength: 3,
  },
];

资源​