Skip to main content

naming-convention

强制对代码库中的所有内容进行命名约定.

💭

该规则需要 类型信息 才能运行，但这会带来性能方面的权衡。

强制命名约定有助于保持代码库的一致性，并减少考虑如何命名变量时的开销。此外，精心设计的样式指南可以帮助传达意图，例如强制所有私有属性以 _ 开头，并且所有全局级常量都用 UPPER_CASE 编写。

¥Enforcing naming conventions helps keep the codebase consistent, and reduces overhead when thinking about how to name a variable. Additionally, a well-designed style guide can help communicate intent, such as by enforcing all private properties begin with an _, and all global-level constants are written in UPPER_CASE.

注意

此规则功能已冻结： =​​=== 此规则由 TypeScript 类型提供支持，因此，如果类型与运行时行为不匹配，则规则可能会报告不准确。它将不再接收新功能，例如新选项。它仍将接受针对其现有功能字段的错误和文档修复，并支持新的 TypeScript 版本。

¥This rule is feature frozen: it will no longer receive new features such as new options. It still will accept bug and documentation fixes for its existing area of features and to support new TypeScript versions.

随着请求的功能越来越模糊，强制命名和/或排序约定的样式规则往往会变得难以理解的复杂。此规则已达到 typescript-eslint 项目维护的合理极限。有关更多信息，请参阅 eslint-plugin:功能冻结命名和排序样式规则。

¥Stylistic rules that enforce naming and/or sorting conventions tend to grow incomprehensibly complex as increasingly obscure features are requested. This rule has reached the limit of what is reasonable for the typescript-eslint project to maintain. See eslint-plugin: Feature freeze naming and sorting stylistic rules for more information.

eslint.config.mjs
export default tseslint.config({
  rules: {
    "@typescript-eslint/naming-convention": "error"
  }
});

在线运行试试这个规则 ↗

示例​

¥Examples

此规则允许你对任何标识符强制执行约定，使用细粒度选择器来创建细粒度的样式指南。

¥This rule allows you to enforce conventions for any identifier, using granular selectors to create a fine-grained style guide.

注意

此规则谨慎行事，仅适用于底部类型、顶部类型以及将字面量类型与原始类型进行比较。

¥This rule only needs type information in specific cases, detailed below.

选项​

¥Options

该规则接受对象数组，每个对象描述不同的命名约定。下面将详细描述每个属性。另请参阅下面的示例部分以获取图示示例。

¥This rule accepts an array of objects, with each object describing a different naming convention. Each property will be described in detail below. Also see the examples section below for illustrated examples.

type Options = {
  // format options
  format:
    | (
        | 'camelCase'
        | 'strictCamelCase'
        | 'PascalCase'
        | 'StrictPascalCase'
        | 'snake_case'
        | 'UPPER_CASE'
      )[]
    | null;
  custom?: {
    regex: string;
    match: boolean;
  };
  leadingUnderscore?:
    | 'forbid'
    | 'require'
    | 'requireDouble'
    | 'allow'
    | 'allowDouble'
    | 'allowSingleOrDouble';
  trailingUnderscore?:
    | 'forbid'
    | 'require'
    | 'requireDouble'
    | 'allow'
    | 'allowDouble'
    | 'allowSingleOrDouble';
  prefix?: string[];
  suffix?: string[];

  // selector options
  selector: Selector | Selector[];
  filter?:
    | string
    | {
        regex: string;
        match: boolean;
      };
  // the allowed values for these are dependent on the selector - see below
  modifiers?: Modifiers<Selector>[];
  types?: Types<Selector>[];
}[];

// the default config is similar to ESLint's camelcase rule but more strict
const defaultOptions: Options = [
  {
    selector: 'default',
    format: ['camelCase'],
    leadingUnderscore: 'allow',
    trailingUnderscore: 'allow',
  },

  {
    selector: 'import',
    format: ['camelCase', 'PascalCase'],
  },

  {
    selector: 'variable',
    format: ['camelCase', 'UPPER_CASE'],
    leadingUnderscore: 'allow',
    trailingUnderscore: 'allow',
  },

  {
    selector: 'typeLike',
    format: ['PascalCase'],
  },
];

格式选项​

¥Format Options

每个选择器都可以具有相同的格式选项集。有关如何应用每个选择器的信息，请参阅 "该规则如何评估名称的格式？"。

¥Every single selector can have the same set of format options. For information about how each selector is applied, see "How does the rule evaluate a name's format?".

format​

format 选项定义标识符的允许格式。此选项接受以下值的数组，并且标识符可以与其中任何一个匹配：

¥The format option defines the allowed formats for the identifier. This option accepts an array of the following values, and the identifier can match any of them:

  • camelCase - 标准 camelCase 格式 - 字符之间不允许有下划线，允许连续大写（即 myID 和 myId 均有效）。

    ¥camelCase - standard camelCase format - no underscores are allowed between characters, and consecutive capitals are allowed (i.e. both myID and myId are valid).

  • PascalCase - 与 camelCase 相同，但第一个字符必须大写。

    ¥PascalCase - same as camelCase, except the first character must be upper-case.

  • snake_case - 标准 snake_case 格式 - 所有字符都必须是小写，并且允许使用下划线。

    ¥snake_case - standard snake_case format - all characters must be lower-case, and underscores are allowed.

  • strictCamelCase - 与 camelCase 相同，但不允许连续大写（即 myId 有效，但 myID 无效）。

    ¥strictCamelCase - same as camelCase, but consecutive capitals are not allowed (i.e. myId is valid, but myID is not).

  • StrictPascalCase - 与 strictCamelCase 相同，但第一个字符必须大写。

    ¥StrictPascalCase - same as strictCamelCase, except the first character must be upper-case.

  • UPPER_CASE - 与 snake_case 相同，但所有字符都必须大写。

    ¥UPPER_CASE - same as snake_case, except all characters must be upper-case.

除了数组，你还可以传递 null。这表示 "此选择器不应检查其格式"。如果你想在应用组选择器后对特定选择器不强制执行特定格式，这会很有用。

¥Instead of an array, you may also pass null. This signifies "this selector shall not have its format checked". This can be useful if you want to enforce no particular format for a specific selector, after applying a group selector.

custom​

custom 选项定义标识符必须（或不能）匹配的自定义正则表达式。此选项允许你对标识符进行更细粒度的控制，从而禁止（或强制）某些模式和子字符串。接受具有以下属性的对象：

¥The custom option defines a custom regex that the identifier must (or must not) match. This option allows you to have a bit more finer-grained control over identifiers, letting you ban (or force) certain patterns and substrings. Accepts an object with the following properties:

  • match - 如果标识符必须与 regex 匹配，则为 true，如果标识符不能与 regex 匹配，则为 false。

    ¥match - true if the identifier must match the regex, false if the identifier must not match the regex.

  • regex - 然后传递到 RegExp 中以创建新正则表达式的字符串：new RegExp(regex)

    ¥regex - a string that is then passed into RegExp to create a new regular expression: new RegExp(regex)

filter​

filter 选项的操作类似于 custom，接受相同形状的对象，不同之处在于它控制是否应将其余配置应用于标识符。

¥The filter option operates similar to custom, accepting the same shaped object, except that it controls if the rest of the configuration should or should not be applied to an identifier.

你可以使用它来包含或排除特定配置中的特定标识符。

¥You can use this to include or exclude specific identifiers from specific configurations.

接受具有以下属性的对象：

¥Accepts an object with the following properties:

  • match - 如果标识符必须与 regex 匹配，则为 true，如果标识符不能与 regex 匹配，则为 false。

    ¥match - true if the identifier must match the regex, false if the identifier must not match the regex.

  • regex - 然后传递到 RegExp 中以创建新正则表达式的字符串：new RegExp(regex)

    ¥regex - a string that is then passed into RegExp to create a new regular expression: new RegExp(regex)

或者，filter 接受正则表达式（new RegExp(filter) 中接受的任何内容）。在这种情况下，它会被视为你已经传递了一个带有正则表达式和 match: true 的对象。

¥Alternatively, filter accepts a regular expression (anything accepted into new RegExp(filter)). In this case, it's treated as if you had passed an object with the regex and match: true.

leadingUnderscore/trailingUnderscore​

leadingUnderscore / trailingUnderscore 选项控制前导/尾随下划线是否被视为有效。接受以下值之一：

¥The leadingUnderscore / trailingUnderscore options control whether leading/trailing underscores are considered valid. Accepts one of the following values:

  • allow - 没有明确强制要求存在单个前导/尾随下划线。

    ¥allow - existence of a single leading/trailing underscore is not explicitly enforced.

  • allowDouble - 没有明确强制要求存在双前导/尾随下划线。

    ¥allowDouble - existence of a double leading/trailing underscore is not explicitly enforced.

  • allowSingleOrDouble - 没有明确强制要求存在单个或双前导/尾随下划线。

    ¥allowSingleOrDouble - existence of a single or a double leading/trailing underscore is not explicitly enforced.

  • forbid - 完全不允许使用前导/尾随下划线。

    ¥forbid - a leading/trailing underscore is not allowed at all.

  • require - 必须包含单个前导/尾随下划线。

    ¥require - a single leading/trailing underscore must be included.

  • requireDouble - 必须包含两个前导/尾随下划线。

    ¥requireDouble - two leading/trailing underscores must be included.

prefix/suffix​

prefix / suffix 选项控制标识符必须存在哪些前缀/后缀字符串。接受字符串数组。

¥The prefix / suffix options control which prefix/suffix strings must exist for the identifier. Accepts an array of strings.

如果提供了这些，则标识符必须以提供的值之一开头。例如，如果你提供 { prefix: ['Class', 'IFace', 'Type'] }，则以下名称有效：ClassBar、IFaceFoo、TypeBaz，但名称 Bang 无效，因为它不包含任何前缀。

¥If these are provided, the identifier must start with one of the provided values. For example, if you provide { prefix: ['Class', 'IFace', 'Type'] }, then the following names are valid: ClassBar, IFaceFoo, TypeBaz, but the name Bang is not valid, as it contains none of the prefixes.

注意：与 上面记录了 一样，前缀在验证格式之前被修剪，因此必须使用 PascalCase 来允许使用前缀 is 的变量（例如 isEnabled）。

¥Note: As documented above, the prefix is trimmed before format is validated, therefore PascalCase must be used to allow variables such as isEnabled using the prefix is.

选择器选项​

¥Selector Options

  • selector 允许你指定要定位的标识符类型。

    ¥selector allows you to specify what types of identifiers to target.

    • 接受一个或一组选择器来定义适用于一个或多个选择器的选项块。

      ¥Accepts one or array of selectors to define an option block that applies to one or multiple selectors.

    • 例如，如果你提供 { selector: ['function', 'variable'] }，则它将对变量和函数节点应用相同的选项。

      ¥For example, if you provide { selector: ['function', 'variable'] }, then it will apply the same option to variable and function nodes.

    • 有关允许的选择器的完整列表，请参阅下面的 允许的选择器、修饰符和类型。

      ¥See Allowed Selectors, Modifiers and Types below for the complete list of allowed selectors.

  • modifiers 允许你指定要精细应用的修饰符，例如可访问性（#private/private/protected/public），或者该事物是否为 static 等。

    ¥modifiers allows you to specify which modifiers to granularly apply to, such as the accessibility (#private/private/protected/public), or if the thing is static, etc.

    • 该名称必须与所有修饰符匹配。

      ¥The name must match all of the modifiers.

    • 例如，如果你提供 { modifiers: ['private','readonly','static'] }，则它只会匹配 private static readonly，而 private 则不会匹配。

      ¥For example, if you provide { modifiers: ['private','readonly','static'] }, then it will only match something that is private static readonly, and something that is just private will not match.

    • 允许以下 modifiers：

      ¥The following modifiers are allowed:

      • abstract,override,private,protected,readonly,static - 匹配任何使用给定修饰符明确声明的成员。

        ¥abstract,override,private,protected,readonly,static - matches any member explicitly declared with the given modifier.

      • async - 匹配任何通过 async 关键字异步的方法、函数或函数变量（例如，不匹配不使用 async 关键字返回 promise 的函数）

        ¥async - matches any method, function, or function variable which is async via the async keyword (e.g. does not match functions that return promises without using async keyword)

      • const - 匹配声明为 const (const x = 1) 的变量。

        ¥const - matches a variable declared as being const (const x = 1).

      • destructured - 匹配通过对象解构模式声明的变量 (const {x, z = 2})。

        ¥destructured - matches a variable declared via an object destructuring pattern (const {x, z = 2}).

        • 请注意，这与重命名的解构属性 (const {x: y, a: b = 2}) 不匹配。

          ¥Note that this does not match renamed destructured properties (const {x: y, a: b = 2}).

      • exported - 匹配从模块导出的任何内容。

        ¥exported - matches anything that is exported from the module.

      • global - 匹配在顶层范围内声明的变量/函数。

        ¥global - matches a variable/function declared in the top-level scope.

      • #private - 匹配任何具有私有标识符（以 # 开头的标识符）的成员

        ¥#private - matches any member with a private identifier (an identifier that starts with #)

      • public - 匹配任何明确声明为 public 或没有可见性修饰符（即隐式公开）的成员。

        ¥public - matches any member that is either explicitly declared as public, or has no visibility modifier (i.e. implicitly public).

      • requiresQuotes - 匹配任何需要引号的名称，因为它不是有效标识符（即其中包含空格、破折号等）。

        ¥requiresQuotes - matches any name that requires quotes as it is not a valid identifier (i.e. has a space, a dash, etc in it).

      • unused - 匹配任何未使用的内容。

        ¥unused - matches anything that is not used.

  • types 允许你指定要匹配的类型。此选项仅支持简单、原始类型（array、boolean、function、number、string）。

    ¥types allows you to specify which types to match. This option supports simple, primitive types only (array,boolean,function,number,string).

    • 该名称必须与其中一种类型匹配。

      ¥The name must match one of the types.

    • 注意 - 使用此选项将需要你使用类型信息进行 lint。

      ¥NOTE - Using this option will require that you lint with type information.

    • 例如，这允许你执行诸如强制 boolean 变量以动词为前缀的操作。

      ¥For example, this lets you do things like enforce that boolean variables are prefixed with a verb.

    • 允许以下 types：

      ¥The following types are allowed:

      • array 匹配任何可分配给 Array<unknown> | null | undefined 的类型

        ¥array matches any type assignable to Array<unknown> | null | undefined

      • boolean 匹配任何可分配给 boolean | null | undefined 的类型

        ¥boolean matches any type assignable to boolean | null | undefined

      • function 匹配任何可分配给 Function | null | undefined 的类型

        ¥function matches any type assignable to Function | null | undefined

      • number 匹配任何可分配给 number | null | undefined 的类型

        ¥number matches any type assignable to number | null | undefined

      • string 匹配任何可分配给 string | null | undefined 的类型

        ¥string matches any type assignable to string | null | undefined

选择器的顺序并不重要。该实现将自动对选择器进行排序，以确保它们从最具体到最不具体的匹配。它将继续按该顺序检查选择器，直到找到与名称匹配的选择器。参见 "规则如何自动对选择器进行排序？"

¥The ordering of selectors does not matter. The implementation will automatically sort the selectors to ensure they match from most-specific to least specific. It will keep checking selectors in that order until it finds one that matches the name. See "How does the rule automatically order selectors?"

允许的选择器、修饰符和类型​

¥Allowed Selectors, Modifiers and Types

选择器有两种类型：单独选择器和分组选择器。

¥There are two types of selectors, individual selectors, and grouped selectors.

单独选择器​

¥Individual Selectors

各个选择器匹配特定的、定义明确的集合。每个单独的选择器之间没有重叠。

¥Individual Selectors match specific, well-defined sets. There is no overlap between each of the individual selectors.

  • classicAccessor - 匹配任何访问器。它指的是附加到 get 和 set 语法的方法。

    ¥classicAccessor - matches any accessor. It refers to the methods attached to get and set syntax.

    • 允许的 modifiers：abstract, override, private, protected, public, requiresQuotes, static.

      ¥Allowed modifiers: abstract, override, private, protected, public, requiresQuotes, static.

    • 允许的 types：array, boolean, function, number, string.

      ¥Allowed types: array, boolean, function, number, string.

  • autoAccessor - 匹配任何自动访问器。自动访问器只是一个以 accessor 关键字开头的类字段。

    ¥autoAccessor - matches any auto-accessor. An auto-accessor is just a class field starting with an accessor keyword.

    • 允许的 modifiers：abstract, override, private, protected, public, requiresQuotes, static.

      ¥Allowed modifiers: abstract, override, private, protected, public, requiresQuotes, static.

    • 允许的 types：array, boolean, function, number, string.

      ¥Allowed types: array, boolean, function, number, string.

  • class - 匹配任何类声明。

    ¥class - matches any class declaration.

    • 允许的 modifiers：abstract, exported, unused.

      ¥Allowed modifiers: abstract, exported, unused.

    • 允许的 types：没有任何。

      ¥Allowed types: none.

  • classMethod - 匹配任何类方法。还匹配具有直接函数表达式或箭头函数表达式值的属性。与访问器不匹配。

    ¥classMethod - matches any class method. Also matches properties that have direct function expression or arrow function expression values. Does not match accessors.

    • 允许的 modifiers：abstract, async, override, #private, private, protected, public, requiresQuotes, static.

      ¥Allowed modifiers: abstract, async, override, #private, private, protected, public, requiresQuotes, static.

    • 允许的 types：没有任何。

      ¥Allowed types: none.

  • classProperty - 匹配任何类属性。不匹配具有直接函数表达式或箭头函数表达式值的属性。

    ¥classProperty - matches any class property. Does not match properties that have direct function expression or arrow function expression values.

    • 允许的 modifiers：abstract, override, #private, private, protected, public, readonly, requiresQuotes, static.

      ¥Allowed modifiers: abstract, override, #private, private, protected, public, readonly, requiresQuotes, static.

    • 允许的 types：array, boolean, function, number, string.

      ¥Allowed types: array, boolean, function, number, string.

  • enum - 匹配任何枚举声明。

    ¥enum - matches any enum declaration.

    • 允许的 modifiers：exported, unused.

      ¥Allowed modifiers: exported, unused.

    • 允许的 types：没有任何。

      ¥Allowed types: none.

  • enumMember - 匹配任何枚举成员。

    ¥enumMember - matches any enum member.

    • 允许的 modifiers：requiresQuotes。

      ¥Allowed modifiers: requiresQuotes.

    • 允许的 types：没有任何。

      ¥Allowed types: none.

  • function - 匹配任何命名函数声明或命名函数表达式。

    ¥function - matches any named function declaration or named function expression.

    • 允许的 modifiers：async, exported, global, unused.

      ¥Allowed modifiers: async, exported, global, unused.

    • 允许的 types：没有任何。

      ¥Allowed types: none.

  • import - 匹配命名空间导入和默认导入（即不匹配命名导入）。

    ¥import - matches namespace imports and default imports (i.e. does not match named imports).

    • 允许的 modifiers：default, namespace.

      ¥Allowed modifiers: default, namespace.

    • 允许的 types：没有任何。

      ¥Allowed types: none.

  • interface - 匹配任何接口声明。

    ¥interface - matches any interface declaration.

    • 允许的 modifiers：exported, unused.

      ¥Allowed modifiers: exported, unused.

    • 允许的 types：没有任何。

      ¥Allowed types: none.

  • objectLiteralMethod - 匹配任何对象字面量方法。还匹配具有直接函数表达式或箭头函数表达式值的属性。与访问器不匹配。

    ¥objectLiteralMethod - matches any object literal method. Also matches properties that have direct function expression or arrow function expression values. Does not match accessors.

    • 允许的 modifiers：async, public, requiresQuotes.

      ¥Allowed modifiers: async, public, requiresQuotes.

    • 允许的 types：没有任何。

      ¥Allowed types: none.

  • objectLiteralProperty - 匹配任何对象字面量属性。不匹配具有直接函数表达式或箭头函数表达式值的属性。

    ¥objectLiteralProperty - matches any object literal property. Does not match properties that have direct function expression or arrow function expression values.

    • 允许的 modifiers：public, requiresQuotes.

      ¥Allowed modifiers: public, requiresQuotes.

    • 允许的 types：array, boolean, function, number, string.

      ¥Allowed types: array, boolean, function, number, string.

  • parameter - 匹配任何函数参数。与参数属性不匹配。

    ¥parameter - matches any function parameter. Does not match parameter properties.

    • 允许的 modifiers：destructured, unused.

      ¥Allowed modifiers: destructured, unused.

    • 允许的 types：array, boolean, function, number, string.

      ¥Allowed types: array, boolean, function, number, string.

  • parameterProperty - 匹配任何参数属性。

    ¥parameterProperty - matches any parameter property.

    • 允许的 modifiers：private, protected, public, readonly.

      ¥Allowed modifiers: private, protected, public, readonly.

    • 允许的 types：array, boolean, function, number, string.

      ¥Allowed types: array, boolean, function, number, string.

  • typeAlias - 匹配任何类型别名声明。

    ¥typeAlias - matches any type alias declaration.

    • 允许的 modifiers：exported, unused.

      ¥Allowed modifiers: exported, unused.

    • 允许的 types：没有任何。

      ¥Allowed types: none.

  • typeMethod - 匹配任何对象类型方法。还匹配具有直接函数表达式或箭头函数表达式值的属性。与访问器不匹配。

    ¥typeMethod - matches any object type method. Also matches properties that have direct function expression or arrow function expression values. Does not match accessors.

    • 允许的 modifiers：public, requiresQuotes.

      ¥Allowed modifiers: public, requiresQuotes.

    • 允许的 types：没有任何。

      ¥Allowed types: none.

  • typeParameter - 匹配任何泛型类型参数声明。

    ¥typeParameter - matches any generic type parameter declaration.

    • 允许的 modifiers：unused。

      ¥Allowed modifiers: unused.

    • 允许的 types：没有任何。

      ¥Allowed types: none.

  • typeProperty - 匹配任何对象类型属性。不匹配具有直接函数表达式或箭头函数表达式值的属性。

    ¥typeProperty - matches any object type property. Does not match properties that have direct function expression or arrow function expression values.

    • 允许的 modifiers：public, readonly, requiresQuotes.

      ¥Allowed modifiers: public, readonly, requiresQuotes.

    • 允许的 types：array, boolean, function, number, string.

      ¥Allowed types: array, boolean, function, number, string.

  • variable - 匹配任何 const / let / var 变量名。

    ¥variable - matches any const / let / var variable name.

    • 允许的 modifiers：async, const, destructured, exported, global, unused.

      ¥Allowed modifiers: async, const, destructured, exported, global, unused.

    • 允许的 types：array, boolean, function, number, string.

      ¥Allowed types: array, boolean, function, number, string.

组选择器​

¥Group Selectors

组选择器是为了方便起见而提供的，本质上是将各个选择器的集合打包在一起。

¥Group Selectors are provided for convenience, and essentially bundle up sets of individual selectors.

  • default - 匹配所有内容。

    ¥default - matches everything.

    • 允许的 modifiers：所有修饰符。

      ¥Allowed modifiers: all modifiers.

    • 允许的 types：没有任何。

      ¥Allowed types: none.

  • accessor - 与 classicAccessor 和 autoAccessor 匹配相同。

    ¥accessor - matches the same as classicAccessor and autoAccessor.

    • 允许的 modifiers：abstract, override, private, protected, public, requiresQuotes, static.

      ¥Allowed modifiers: abstract, override, private, protected, public, requiresQuotes, static.

    • 允许的 types：array, boolean, function, number, string.

      ¥Allowed types: array, boolean, function, number, string.

  • memberLike - 与 classicAccessor、autoAccessor、enumMember、method、parameterProperty、property 匹配相同。

    ¥memberLike - matches the same as classicAccessor, autoAccessor, enumMember, method, parameterProperty, property.

    • 允许的 modifiers：abstract, async, override, #private, private, protected, public, readonly, requiresQuotes, static.

      ¥Allowed modifiers: abstract, async, override, #private, private, protected, public, readonly, requiresQuotes, static.

    • 允许的 types：没有任何。

      ¥Allowed types: none.

  • method - 与 classMethod、objectLiteralMethod、typeMethod 匹配相同。

    ¥method - matches the same as classMethod, objectLiteralMethod, typeMethod.

    • 允许的 modifiers：abstract, async, override, #private, private, protected, public, readonly, requiresQuotes, static.

      ¥Allowed modifiers: abstract, async, override, #private, private, protected, public, readonly, requiresQuotes, static.

    • 允许的 types：没有任何。

      ¥Allowed types: none.

  • property - 与 classProperty、objectLiteralProperty、typeProperty 匹配相同。

    ¥property - matches the same as classProperty, objectLiteralProperty, typeProperty.

    • 允许的 modifiers：abstract, async, override, #private, private, protected, public, readonly, requiresQuotes, static.

      ¥Allowed modifiers: abstract, async, override, #private, private, protected, public, readonly, requiresQuotes, static.

    • 允许的 types：array, boolean, function, number, string.

      ¥Allowed types: array, boolean, function, number, string.

  • typeLike - 与 class、enum、interface、typeAlias、typeParameter 匹配相同。

    ¥typeLike - matches the same as class, enum, interface, typeAlias, typeParameter.

    • 允许的 modifiers：abstract, unused.

      ¥Allowed modifiers: abstract, unused.

    • 允许的 types：没有任何。

      ¥Allowed types: none.

  • variableLike - 与 function、parameter 和 variable 匹配相同。

    ¥variableLike - matches the same as function, parameter and variable.

    • 允许的 modifiers：async, unused.

      ¥Allowed modifiers: async, unused.

    • 允许的 types：没有任何。

      ¥Allowed types: none.

常见问题​

¥FAQ

这是一个很大的规则，并且有很多文档。以下是人们经常询问或通过反复试验找出的一些澄清。

¥This is a big rule, and there's a lot of docs. Here are a few clarifications that people often ask about or figure out via trial-and-error.

规则如何评估选择器？​

¥How does the rule evaluate a selector?

每个选择器都按以下方式检查：

¥Each selector is checked in the following way:

  1. 检查 filter

    ¥check the filter

    1. 如果省略 filter → 跳过此步骤。

      ¥if filter is omitted → skip this step.

    2. 如果名称与 filter 匹配 → 继续评估此选择器。

      ¥if the name matches the filter → continue evaluating this selector.

    3. 如果名称与 filter 不匹配 → 跳过此选择器并继续下一个选择器。

      ¥if the name does not match the filter → skip this selector and continue to the next selector.

  2. 检查 selector

    ¥check the selector

    1. 如果 selector 是一个单独的选择器 → 名称的类型必须是该类型。

      ¥if selector is one individual selector → the name's type must be of that type.

    2. 如果 selector 是组选择器 → 名称的类型必须是分组类型之一。

      ¥if selector is a group selector → the name's type must be one of the grouped types.

    3. 如果 selector 是选择器数组 → 对数组中的每个选择器应用上述操作。

      ¥if selector is an array of selectors → apply the above for each selector in the array.

  3. 检查 types

    ¥check the types

    1. 如果省略 types → 跳过此步骤。

      ¥if types is omitted → skip this step.

    2. 如果名称在 types 中有类型 → 继续评估此选择器。

      ¥if the name has a type in types → continue evaluating this selector.

    3. 如果名称在 types 中没有类型 → 跳过此选择器并继续下一个选择器。

      ¥if the name does not have a type in types → skip this selector and continue to the next selector.

如果名称符合以下条件，则被视为传递配置：

¥A name is considered to pass the config if it:

  1. 匹配一个选择器并通过该选择器的所有格式检查。

    ¥Matches one selector and passes all of that selector's format checks.

  2. 不匹配任何选择器。

    ¥Matches no selectors.

如果名称与一个选择器匹配并且未通过选择器格式检查，则该名称将被视为配置失败。

¥A name is considered to fail the config if it matches one selector and fails one that selector's format checks.

规则如何自动对选择器进行排序？​

¥How does the rule automatically order selectors?

每个标识符应该与一个选择器完全匹配。它可能匹配多个组选择器 - 但只有一个选择器。考虑到这一点 - 基本排序顺序如下：

¥Each identifier should match exactly one selector. It may match multiple group selectors - but only ever one selector. With that in mind - the base sort order works out to be:

  1. 单独选择器

    ¥Individual Selectors

  2. 分组选择器

    ¥Grouped Selectors

  3. 默认选择器

    ¥Default Selector

在每个类别中，根据提供的选择器选项进行一些进一步的排序：

¥Within each of these categories, some further sorting occurs based on what selector options are supplied:

  1. filter 的优先级高于其他一切。

    ¥filter is given the highest priority above all else.

  2. types

  3. modifiers

  4. 其他一切

    ¥everything else

例如，如果你提供以下配置：

¥For example, if you provide the following config:

[
  /* 1 */ { selector: 'default', format: ['camelCase'] },
  /* 2 */ { selector: 'variable', format: ['snake_case'] },
  /* 3 */ { selector: 'variable', types: ['boolean'], format: ['UPPER_CASE'] },
  /* 4 */ { selector: 'variableLike', format: ['PascalCase'] },
];

然后对于代码 const x = 1，规则将按以下顺序验证选择器：3, 2, 4, 1.为了清楚地阐明它：

¥Then for the code const x = 1, the rule will validate the selectors in the following order: 3, 2, 4, 1. To clearly spell it out:

  • (3) 首先被测试，因为它有 types 并且是一个单独的选择器。

    ¥(3) is tested first because it has types and is an individual selector.

  • 接下来测试 (2)，因为它是一个单独的选择器。

    ¥(2) is tested next because it is an individual selector.

  • 接下来测试 (4)，因为它是分组选择器。

    ¥(4) is tested next as it is a grouped selector.

  • (1) 最后测试，因为它是基本默认选择器。

    ¥(1) is tested last as it is the base default selector.

值得注意的是，虽然应用了此顺序，但所有选择器可能不会在名称上运行。这在 "该规则如何评估名称的格式？" 中有解释

¥Its worth noting that whilst this order is applied, all selectors may not run on a name. This is explained in "How does the rule evaluate a name's format?"

该规则如何评估名称的格式？​

¥How does the rule evaluate a name's format?

检查标识符的格式时，按以下顺序检查：

¥When the format of an identifier is checked, it is checked in the following order:

  1. 验证前导下划线

    ¥validate leading underscore

  2. 验证尾随下划线

    ¥validate trailing underscore

  3. 验证前缀

    ¥validate prefix

  4. 验证后缀

    ¥validate suffix

  5. 验证自定义

    ¥validate custom

  6. 验证格式

    ¥validate format

对于步骤 1-4，如果标识符与选项匹配，则匹配部分将被删除。这样做是为了让你可以应用 PascalCase 等格式，而不必担心前缀或下划线导致其不匹配。

¥For steps 1-4, if the identifier matches the option, the matching part will be removed. This is done so that you can apply formats like PascalCase without worrying about prefixes or underscores causing it to not match.

最后要注意的是，如果名称通过此修剪过程变为空，则认为它与所有 format 匹配。这可能有用的一个例子是通用类型参数，你希望所有名称都以 T 为前缀，但也希望允许单字符 T 名称。

¥One final note is that if the name were to become empty via this trimming process, it is considered to match all formats. An example of where this might be useful is for generic type parameters, where you want all names to be prefixed with T, but also want to allow for the single character T name.

这里有一些例子来帮助说明

¥Here are some examples to help illustrate

名称：_IMyInterface 选择器：

¥Name: _IMyInterface Selector:

{
  "leadingUnderscore": "require",
  "prefix": ["I"],
  "format": ["UPPER_CASE", "StrictPascalCase"]
}

  1. name = _IMyInterface

  2. 验证前导下划线

    ¥validate leading underscore

    1. 提供了配置

      ¥config is provided

    2. 检查名称 → 通过

      ¥check name → pass

    3. 修剪下划线 → name = IMyInterface

      ¥Trim underscore → name = IMyInterface

  3. 验证尾随下划线

    ¥validate trailing underscore

    1. 未提供配置 → 跳过

      ¥config is not provided → skip

  4. 验证前缀

    ¥validate prefix

    1. 提供了配置

      ¥config is provided

    2. 检查名称 → 通过

      ¥check name → pass

    3. 修剪前缀 → name = MyInterface

      ¥Trim prefix → name = MyInterface

  5. 验证后缀

    ¥validate suffix

    1. 未提供配置 → 跳过

      ¥config is not provided → skip

  6. 验证自定义

    ¥validate custom

    1. 未提供配置 → 跳过

      ¥config is not provided → skip

  7. 验证格式

    ¥validate format

    1. 对于每种格式...

      ¥for each format...

      1. format = 'UPPER_CASE'

        1. 检查格式→失败。

          ¥check format → fail.

          • 请注意，如果你提供多种格式 - 名称只需匹配其中一个！

            ¥Important to note that if you supply multiple formats - the name only needs to match one of them!

      2. format = 'StrictPascalCase'

        1. 检查格式→成功。

          ¥check format → success.

  8. success

名称：IMyInterface 选择器：

¥Name: IMyInterface Selector:

{
  "format": ["StrictPascalCase"],
  "trailingUnderscore": "allow",
  "custom": {
    "regex": "^I[A-Z]",
    "match": false
  }
}

  1. name = IMyInterface

  2. 验证前导下划线

    ¥validate leading underscore

    1. 未提供配置 → 跳过

      ¥config is not provided → skip

  3. 验证尾随下划线

    ¥validate trailing underscore

    1. 提供了配置

      ¥config is provided

    2. 检查名称 → 通过

      ¥check name → pass

    3. 修剪下划线 → name = IMyInterface

      ¥Trim underscore → name = IMyInterface

  4. 验证前缀

    ¥validate prefix

    1. 未提供配置 → 跳过

      ¥config is not provided → skip

  5. 验证后缀

    ¥validate suffix

    1. 未提供配置 → 跳过

      ¥config is not provided → skip

  6. 验证自定义

    ¥validate custom

    1. 提供了配置

      ¥config is provided

    2. regex = new RegExp("^I[A-Z]")

    3. regex.test(name) === custom.match

    4. 失败 → 报告并退出

      ¥fail → report and exit

如果我向组选择器提供 modifiers 会发生什么？​

¥What happens if I provide a modifiers to a Group Selector?

一些组选择器接受 modifiers。在大多数情况下，它们的工作方式与单个选择器完全相同。有一个例外，即修饰符可能不适用于组选择器涵盖的所有单独选择器。

¥Some group selectors accept modifiers. For the most part these will work exactly the same as with individual selectors. There is one exception to this in that a modifier might not apply to all individual selectors covered by a group selector.

例如 - memberLike 包含 enumMember 选择器，并且允许使用 protected 修饰符。enumMember 永远不可能是 protected，这意味着以下配置永远不会匹配任何 enumMember：

¥For example - memberLike includes the enumMember selector, and it allows the protected modifier. An enumMember can never ever be protected, which means that the following config will never match any enumMember:

{
  "selector": "memberLike",
  "modifiers": ["protected"]
}

为了帮助匹配，无法指定可访问性的成员将始终具有 public 修饰符。这意味着以下配置将始终匹配任何 enumMember：

¥To help with matching, members that cannot specify an accessibility will always have the public modifier. This means that the following config will always match any enumMember:

{
  "selector": "memberLike",
  "modifiers": ["public"]
}

示例​

¥Examples

强制所有变量、函数和属性遵循驼峰命名法​

¥Enforce that all variables, functions and properties follow are camelCase

{
  "@typescript-eslint/naming-convention": [
    "error",
    { "selector": "variableLike", "format": ["camelCase"] }
  ]
}

强制私有成员以下划线为前缀​

¥Enforce that private members are prefixed with an underscore

{
  "@typescript-eslint/naming-convention": [
    "error",
    {
      "selector": "memberLike",
      "modifiers": ["private"],
      "format": ["camelCase"],
      "leadingUnderscore": "require"
    }
  ]
}

强制布尔变量以允许的动词为前缀​

¥Enforce that boolean variables are prefixed with an allowed verb

注意：与 上面记录了 一样，在验证格式之前会修剪前缀，因此必须使用 PascalCase 来允许诸如 isEnabled 之类的变量。

¥Note: As documented above, the prefix is trimmed before format is validated, thus PascalCase must be used to allow variables such as isEnabled.

{
  "@typescript-eslint/naming-convention": [
    "error",
    {
      "selector": "variable",
      "types": ["boolean"],
      "format": ["PascalCase"],
      "prefix": ["is", "should", "has", "can", "did", "will"]
    }
  ]
}

强制所有变量都采用驼峰式命名或大写命名​

¥Enforce that all variables are either in camelCase or UPPER_CASE

{
  "@typescript-eslint/naming-convention": [
    "error",
    {
      "selector": "variable",
      "format": ["camelCase", "UPPER_CASE"]
    }
  ]
}

强制所有 const 变量均采用 UPPER_CASE​

¥Enforce that all const variables are in UPPER_CASE

{
  "@typescript-eslint/naming-convention": [
    "error",
    {
      "selector": "variable",
      "modifiers": ["const"],
      "format": ["UPPER_CASE"]
    }
  ]
}

强制类型参数（泛型）以 T 为前缀​

¥Enforce that type parameters (generics) are prefixed with T

这允许你模拟旧的 generic-type-naming 规则。

¥This allows you to emulate the old generic-type-naming rule.

{
  "@typescript-eslint/naming-convention": [
    "error",
    {
      "selector": "typeParameter",
      "format": ["PascalCase"],
      "prefix": ["T"]
    }
  ]
}

强制接口名称不以 I 开头​

¥Enforce that interface names do not begin with an I

这允许你模拟旧的 interface-name-prefix 规则。

¥This allows you to emulate the old interface-name-prefix rule.

{
  "@typescript-eslint/naming-convention": [
    "error",
    {
      "selector": "interface",
      "format": ["PascalCase"],
      "custom": {
        "regex": "^I[A-Z]",
        "match": false
      }
    }
  ]
}

强制函数名称采用 camelCase 或 PascalCase​

¥Enforce that function names are either in camelCase or PascalCase

函数名称通常为 camelCase，但 UI 库组件（尤其是 JSX，例如 React 和 Solid）使用 PascalCase 来将它们与内在元素区分开来。如果你正在编写函数组件，请考虑允许函数同时使用 camelCase 和 PascalCase。

¥Function names are typically camelCase, but UI library components (especially JSX, such as React and Solid) use PascalCase to distinguish them from intrinsic elements. If you are writing function components, consider allowing both camelCase and PascalCase for functions.

{
  "@typescript-eslint/naming-convention": [
    "error",
    {
      "selector": "function",
      "format": ["camelCase", "PascalCase"]
    }
  ]
}

强制变量和函数名称采用驼峰命名法​

¥Enforce that variable and function names are in camelCase

这允许你使用相同的模式对多种类型进行 lint 处理。

¥This allows you to lint multiple type with same pattern.

{
  "@typescript-eslint/naming-convention": [
    "error",
    {
      "selector": ["variable", "function"],
      "format": ["camelCase"],
      "leadingUnderscore": "allow"
    }
  ]
}

忽略需要引号的属性​

¥Ignore properties that require quotes

有时你必须使用违反约定的带引号的名称（例如，HTTP 标头）。如果这在你的代码库中很常见，那么你有几个选择。

¥Sometimes you have to use a quoted name that breaks the convention (for example, HTTP headers). If this is a common thing in your codebase, then you have a few options.

如果你只是想允许所有需要引号的属性名称，则可以使用 requiresQuotes 修饰符匹配任何需要引号的属性名称，并使用 format: null 忽略该名称。

¥If you simply want to allow all property names that require quotes, you can use the requiresQuotes modifier to match any property name that requires quoting, and use format: null to ignore the name.

{
  "@typescript-eslint/naming-convention": [
    "error",
    {
      "selector": [
        "classProperty",
        "objectLiteralProperty",
        "typeProperty",
        "classMethod",
        "objectLiteralMethod",
        "typeMethod",
        "accessor",
        "enumMember",
      ],
      "format": null,
      "modifiers": ["requiresQuotes"],
    },
  ],
}

如果你有一个小的已知异常列表，则可以使用 filter 选项仅忽略这些特定名称：

¥If you have a small and known list of exceptions, you can use the filter option to ignore these specific names only:

{
  "@typescript-eslint/naming-convention": [
    "error",
    {
      "selector": "property",
      "format": ["strictCamelCase"],
      "filter": {
        // you can expand this regex to add more allowed names
        "regex": "^(Property-Name-One|Property-Name-Two)$",
        "match": false,
      },
    },
  ],
}

你可以使用 filter 选项忽略带有特定字符的名称：

¥You can use the filter option to ignore names with specific characters:

{
  "@typescript-eslint/naming-convention": [
    "error",
    {
      "selector": "property",
      "format": ["strictCamelCase"],
      "filter": {
        // you can expand this regex as you find more cases that require quoting that you want to allow
        "regex": "[- ]",
        "match": false,
      },
    },
  ],
}

请注意，没有办法忽略任何带引号的名称 - 仅允许需要引用的名称。这是有意的 - 在名称周围添加引号并不是正确命名的应急方案。如果你想要特定名称的应急方案 - 你应该可以使用 eslint-disable 注释。

¥Note that there is no way to ignore any name that is quoted - only names that are required to be quoted. This is intentional - adding quotes around a name is not an escape hatch for proper naming. If you want an escape hatch for a specific name - you should can use an eslint-disable comment.

忽略解构名称​

¥Ignore destructured names

有时你可能希望允许解构属性保留其原始名称，即使它打破了你的命名约定。

¥Sometimes you might want to allow destructured properties to retain their original name, even if it breaks your naming convention.

你可以使用 destructured 修饰符来匹配这些名称，并明确设置 format: null 以不应用格式：

¥You can use the destructured modifier to match these names, and explicitly set format: null to apply no formatting:

{
  "@typescript-eslint/naming-convention": [
    "error",
    {
      "selector": "variable",
      "modifiers": ["destructured"],
      "format": null,
    },
  ],
}

强制代码库遵循 ESLint 的 camelcase 约定​

¥Enforce the codebase follows ESLint's camelcase conventions

{
  "camelcase": "off",
  "@typescript-eslint/naming-convention": [
    "error",
    {
      "selector": "default",
      "format": ["camelCase"]
    },

    {
      "selector": "variable",
      "format": ["camelCase", "UPPER_CASE"]
    },
    {
      "selector": "parameter",
      "format": ["camelCase"],
      "leadingUnderscore": "allow"
    },

    {
      "selector": "memberLike",
      "modifiers": ["private"],
      "format": ["camelCase"],
      "leadingUnderscore": "require"
    },

    {
      "selector": "typeLike",
      "format": ["PascalCase"]
    }
  ]
}

何时不使用它​

¥When Not To Use It

这条规则可能非常严格。如果你对强制执行命名约定没有强烈的需求，我们建议你仅使用它来标记严重违反命名标准的行为。如果你有类似的流程，请考虑记录你的命名约定并在代码审查中强制执行它们。

¥This rule can be very strict. If you don't have strong needs for enforcing naming conventions, we recommend using it only to flag very egregious violations of your naming standards. Consider documenting your naming conventions and enforcing them in code review if you have processes like that.

如果你不想强制执行任何内容的命名约定，则可以禁用此规则。

¥If you do not want to enforce naming conventions for anything, you can disable this rule.

但是，请记住，不一致的风格可能会损害项目的可读性。我们建议，如果你关心命名约定，请为此规则选择一个最适合你的项目的选项。

¥However, keep in mind that inconsistent style can harm readability in a project. We recommend that if you care about naming conventions, pick a single option for this rule that works best for your project.

Type checked lint rules are more powerful than traditional lint rules, but also require configuring type checked linting.

See Troubleshooting > Linting with Type Information > Performance if you experience performance degradations after enabling type checked rules.

资源​