useFilenamingConvention

JavaScript (and super languages)

摘要

¥Summary

规则生效日期：v1.5.0

¥Rule available since: v1.5.0
诊断类别：lint/style/useFilenamingConvention

¥Diagnostic Category: lint/style/useFilenamingConvention
此规则没有修复方案。

¥This rule doesn’t have a fix.
此规则的默认严重级别为 information。

¥The default severity of this rule is information.
来源：

¥Sources:
- 灵感来自 unicorn/filename-case
  
  ¥Inspired from unicorn/filename-case

如何配置

¥How to configure

1
{
2
  "linter": {
3
    "rules": {
4
      "style": {
5
        "useFilenamingConvention": "error"
6
      }
7
    }
8
  }
9
}

描述

¥Description

强制相对导入的文件扩展名。

¥Enforce naming conventions for JavaScript and TypeScript filenames.

强制命名约定有助于保持代码库的一致性。

¥Enforcing naming conventions helps to keep the codebase consistent.

文件名由两部分组成：文件名和一组连续的扩展名。例如，my-filename.test.js 的名称为 my-filename，并且有两个连续的扩展名：.test 和 .js。

¥A filename consists of two parts: a name and a set of consecutive extensions. For instance, my-filename.test.js has my-filename as name, and two consecutive extensions: .test and .js.

默认情况下，该规则确保文件名属于 camelCase、kebab-case 或 snake_case 类型，或者与文件中某个导出项的名称相同。默认情况下，该规则确保文件扩展名属于 camelCase、kebab-case 或 snake_case 类型。

¥By default, the rule ensures that the name is either in camelCase, kebab-case, snake_case, or equal to the name of one export in the file. By default, the rule ensures that the extensions are either in camelCase, kebab-case, or snake_case.

该规则支持以下异常：

¥The rule supports the following exceptions:

文件名可以以点号、加号或美元符号开头，也可以带有下划线 _ 前缀和后缀。例如，.filename.js、+filename.js、$filename.js、__filename__.js，甚至 .__filename__.js。

¥The name of the file can start with a dot, a plus sign, or a dollar sign, be prefixed and suffixed by underscores _. For example, .filename.js, +filename.js, $filename.js, __filename__.js, or even .__filename__.js.
- Sveltekit 和 Vike 使用在文件名前加加号的惯例。
  
  ¥The convention of prefixing a filename with a plus sign is used by Sveltekit and Vike.
- TanStack Start 使用在文件名前添加美元符号的约定来实现基于文件的路由。
  
  ¥The convention of prefixing a filename with a dollar sign is used by TanStack Start for file-based routing.
此外，规则支持 Next.js、SolidStart、Nuxt 和 Astro 的动态路由语法。例如 [...slug].js 和 [[...slug]].js 是有效的文件名。

¥Also, the rule supports dynamic route syntaxes of Next.js, SolidStart, Nuxt, and Astro. For example [...slug].js and [[...slug]].js are valid filenames.

请注意，如果你指定了 match 选项，则之前的异常将不再被处理。

¥Note that if you specify the match option, the previous exceptions will no longer be handled.

忽略某些文件

¥Ignoring some files

有时你想完全忽略某些文件。Biome 忽略注释不能使用，因为该规则适用于文件名而不是文件内容。要忽略文件，你可以使用 overrides。如果你想忽略 test 目录中的所有文件，则可以仅针对这些文件禁用规则：

¥Sometimes you want to completely ignore some files. Biome ignore comments cannot be used because the rule applies on filenames not file contents. To ignore files, you can use overrides. If you want to ignore all files in the test directory, then you can disable the rule for those files only:

1
{
2
  "overrides": [
3
    {
4
       "includes": ["test/**/*"],
5
       "linter": {
6
         "rules": {
7
           "style": {
8
             "useFilenamingConvention": "off"
9
           }
10
         }
11
       }
12
    }
13
  ]
14
}

选项

¥Options

规则提供了几个选项，详见以下小节。

¥The rule provides several options that are detailed in the following subsections.

1
{
2
  "linter": {
3
    "rules": {
4
      "style": {
5
        "useFilenamingConvention": {
6
          "options": {
7
            "strictCase": false,
8
            "requireAscii": true,
9
            "match": "%?(.+?)[.](.+)", // Since v2.0.0
10
            "filenameCases": [
11
              "camelCase",
12
              "export"
13
            ]
14
          }
15
        }
16
      }
17
    }
18
  }
19
}

strictCase

当此选项设置为 true 时，它禁止在 camelCase 和 PascalCase 中使用连续的大写字符。例如，当选项设置为 true 时，agentID 将抛出错误。此名称应重命名为 agentId。

¥When this option is set to true, it forbids consecutive uppercase characters in camelCase and PascalCase. For instance, when the option is set to true, agentID will throw an error. This name should be renamed to agentId.

当选项设置为 false 时，允许连续的大写字符。agentID 非常有效。

¥When the option is set to false, consecutive uppercase characters are allowed. agentID is so valid.

默认：true

¥Default: true

requireAscii

当此选项设置为 true 时，它禁止包含非 ASCII 字符的名称。例如，当选项设置为 true 时，café 或 안녕하세요 将抛出错误。

¥When this option is set to true, it forbids names that include non-ASCII characters. For instance, when the option is set to true, café or 안녕하세요 will throw an error.

当选项设置为 false 时，名称可能包含非 ASCII 字符。café 和 안녕하세요 非常有效。

¥When the option is set to false, a name may include non-ASCII characters. café and 안녕하세요 are so valid.

默认：true

¥Default: true

match

match 定义了一个正则表达式，文件名必须匹配该表达式。如果正则表达式包含捕获组，则第一个捕获组被视为文件名，第二个捕获组被视为以点号分隔的文件扩展名。

¥match defines a regular expression that the filename must match. If the regex has capturing groups, then the first capture is considered as the filename and the second one as file extensions separated by dots.

例如，给定正则表达式 %?(.+?)\.(.+) 和文件名 %index.d.ts，文件名与正则表达式匹配，并捕获两个结果：index 和 d.ts。捕获的内容会与 filenameCases 进行比较。请注意，我们使用非贪婪量词 +?，以便在遇到下一个字符 (.) 时停止捕获。如果我们改用贪婪量词 +，那么捕获结果可以是 index.d 和 ts。

¥For example, given the regular expression %?(.+?)\.(.+) and the filename %index.d.ts, the filename matches the regular expression with two captures: index and d.ts. The captures are checked against filenameCases. Note that we use the non-greedy quantifier +? to stop capturing as soon as we met the next character (.). If we use the greedy quantifier + instead, then the captures could be index.d and ts.

正则表达式支持以下语法：

¥The regular expression supports the following syntaxes:

贪婪量词 *、?、+、{n}、{n,m}、{n,}、{m}

¥Greedy quantifiers *, ?, +, {n}, {n,m}, {n,}, {m}
非贪婪量词 *?、??、+?、{n}?、{n,m}?、{n,}?、{m}?

¥Non-greedy quantifiers *?, ??, +?, {n}?, {n,m}?, {n,}?, {m}?
任何字符匹配器 .

¥Any character matcher .
更改已建立语法的格式。

¥Character classes [a-z], [xyz], [^a-z]
替代 |

¥Alternations |
捕获组 ()

¥Capturing groups ()
非捕获组 (?:)

¥Non-capturing groups (?:)
不区分大小写的组 (?i:) 和区分大小写的组 (?-i:)

¥Case-insensitive groups (?i:) and case-sensitive groups (?-i:)
包含所有特殊字符和常规字符串转义字符 \f、\n、\r、\t、\v 的有限转义字符集。请注意，你还可以使用字符类转义特殊字符。例如，\$ 和 [$] 是两个有效的模式，它们可以转义 $。

¥A limited set of escaped characters including all special characters and regular string escape characters \f, \n, \r, \t, \v. Note that you can also escape special characters using character classes. For example, \$ and [$] are two valid patterns that escape $.

filenameCases

默认情况下，规则强制文件名为 camelCase、kebab-case、snake_case 或等于文件中一个导出的名称。

¥By default, the rule enforces that the filename is either in camelCase, kebab-case, snake_case, or equal to the name of one export in the file.

你可以通过设置 filenameCases 选项来强制执行更严格的约定。filenameCases 接受以下情况中的一组情况：camelCase、kebab-case、PascalCase、snake_case 和 export。

¥You can enforce a stricter convention by setting filenameCases option. filenameCases accepts an array of cases among the following cases: camelCase, kebab-case, PascalCase, snake_case, and export.

此选项也适用于文件扩展名。无论 filenameCases 的设置如何，始终允许使用小写扩展名。

¥This option also applies to the file extensions. Extensions in lowercase are always allowed regardless of how filenameCases is set.