noRestrictedImports

JavaScript (and super languages)

摘要

¥Summary

规则生效日期：v1.6.0

¥Rule available since: v1.6.0
诊断类别：lint/style/noRestrictedImports

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

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

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

¥Sources:
- 与 no-restricted-imports 相同
  
  ¥Same as no-restricted-imports
- 与 @typescript-eslint/no-restricted-imports 相同
  
  ¥Same as @typescript-eslint/no-restricted-imports

如何配置

¥How to configure

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

描述

¥Description

当通过 import 或 require 加载时，禁止指定模块。

¥Disallow specified modules when loaded by import or require.

示例

¥Examples

1
{
2
    "noRestrictedImports": {
3
        "options": {
4
            "paths": {
5
                "lodash": "Using lodash is not encouraged",
6
                "underscore": "Using underscore is not encouraged"
7
            }
8
        }
9
    }
10
}

1
{
2
  "linter": {
3
    "rules": {
4
      "style": {
5
        "noRestrictedImports": {
6
          "options": {
7
            "paths": {
8
              "lodash": "Using lodash is not encouraged.",
9
              "underscore": "",
10
              "import-foo": {
11
                "importNames": [
12
                  "Bar"
13
                ]
14
              },
15
              "import-bar": {
16
                "allowImportNames": [
17
                  "Bar"
18
                ]
19
              }
20
            },
21
            "patterns": [
22
              {
23
                "group": [
24
                  "import-foo/*",
25
                  "!import-foo/bar"
26
                ]
27
              }
28
            ]
29
          }
30
        }
31
      }
32
    }
33
  }
34
}

无效

¥Invalid

1
import "lodash";

code-block.js:1:8 lint/style/noRestrictedImports ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ⚠ Using lodash is not encouraged.
  
  > 1 │ import “lodash”;
      │        ^^^^^^^^
    2 │

1
import "underscore";

code-block.js:1:8 lint/style/noRestrictedImports ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ⚠ Do not import ‘underscore’.
  
  > 1 │ import “underscore”;
      │        ^^^^^^^^^^^^
    2 │

1
import { Bar } from "import-foo";

code-block.js:1:10 lint/style/noRestrictedImports ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ⚠ Do not import ‘Bar’ from ‘import-foo’.
  
  > 1 │ import { Bar } from “import-foo”;
      │          ^^^
    2 │

1
const underscore = await import("underscore");

code-block.js:1:33 lint/style/noRestrictedImports ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ⚠ Do not import ‘underscore’.
  
  > 1 │ const underscore = await import(“underscore”);
      │                                 ^^^^^^^^^^^^
    2 │

1
const lodash = require("lodash");

code-block.js:1:24 lint/style/noRestrictedImports ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ⚠ Using lodash is not encouraged.
  
  > 1 │ const lodash = require(“lodash”);
      │                        ^^^^^^^^
    2 │

1
import foo from 'import-foo/foo';

code-block.js:1:17 lint/style/noRestrictedImports ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ⚠ Do not import ‘import-foo/foo’.
  
  > 1 │ import foo from ‘import-foo/foo’;
      │                 ^^^^^^^^^^^^^^^^
    2 │

有效

¥Valid

1
import "allowed-import";
2
const myImport = await import("allowed-import");
3
const myImport = require("allowed-import");

1
import foo from 'import-foo';
2
import bar from 'import-foo/bar';

支持的导入语法

¥Supported Import Syntaxes

该规则尝试解析导入的上下文，以查看是否从给定模块导入了一个或多个允许的导入名称。

¥The rule tries to parse the context of the import to see if only one or more of the allowed import names have been imported from a given module.

支持以下所有导入语法：

¥All of the following import syntaxes are supported:

静态 `import`（和 re-`export`）声明

¥Static import (and re-export) declarations

支持普通的静态 ESM import 声明：

¥Normal static ESM import declarations are supported:

1
// Static `import` declaration:
2
// https://web.nodejs.cn/en-US/docs/Web/JavaScript/Reference/Statements/import
3

4
import "sideeffect-import";
5
import * as alias1 from "namespace-import";
6
import { export1, export2 as alias2, "string-name" as alias3, default as defaultExport /* … */ } from "named-import";
7
import defaultExport from "default-import";
8
import defaultExport, * as alias5 from "default+namespace-import";
9
import defaultExport, { export1 /* … */ } from "default+named-import";
10

11
export * from "namespace-import";
12
export { export1, export2 as alias2, "string-name" as alias3, default as defaultExport /* … */ } from "named-import";

也支持 TypeScript 特有的仅类型导入：

¥The TypeScript-specific type-only imports are also supported:

1
// TypeScript-specific type-only `import` declaration:
2
// https://ts.nodejs.cn/docs/handbook/modules/reference.html#type-only-imports-and-exports
3

4
import { type export1, type export2 as alias2, type "string-name" as alias3, type default as defaultExport /* … */ } from "named-import";
5
import type { export1, export2 as alias2, "string-name" as alias3, default as defaultExport /* … */ } from "named-import";
6
import type defaultExport from "default-import";

动态 `import()` 调用

¥Dynamic import() calls

动态 ESM import() 调用也受支持。由于导入是在运行时执行的，因此并非总是能够确定正在使用的导入名称。尽管如此，该规则仍会尝试检测以下常见用法模式，其中导入的名称集是静态确定的：

¥Dynamic ESM import() calls are also supported. Because the import is performed at runtime, it is not always possible to determine which import names are being used. Nevertheless, the rule tries to detect the following common usage patterns where the set of imported names is determined statically:

1
// Dynamic `import()` calls:
2
// https://web.nodejs.cn/en-US/docs/Web/JavaScript/Reference/Operators/import
3

4
import('sideeffect-import');
5
await import('sideeffect-import');
6

7
// ...using await + destructuring-assignment:
8
const alias1 = await import('namespace-import');
9
const { default: defaultExport } = await import('default-import')
10
const { export1, export2: alias2, "string-name": alias3, default: defaultExport /* … */ } = await import("named-import");
11

12
// ...using then() with arrow-function + destructuring parameters:
13
import('namespace-import').then(alias1 => { /* … */ });
14
import('namespace-import').then((alias1) => { /* … */ });
15
import('default-import').then(({ default: defaultExport }) => { /* … */ });
16
import('named-import').then(({ export1, export2: alias2, "string-name": alias3, default: defaultExport /* … */ }) => { /* … */ });
17

18
// ...using then() with function + destructuring parameters:
19
import('namespace-import').then(function(alias1) { /* … */ });
20
import('default-import').then(function({ default: defaultExport }) { /* … */ });
21
import('named-import').then(function({ export1, export2: alias2, "string-name": alias3, default: defaultExport /* … */ }) { /* … */ });
22

23
// Standalone `import('...')` calls that appear in some other
24
// unrecognized context will be treated as a namespace import,
25
// because the return value of `import('...')` is a namespace object:
26

27
myFunction(...args, import("namespace-import"), ...args)

动态 `require()` 调用

¥Dynamic require() calls

也支持 NodeJS 风格的 require() 调用。由于 require() 的工作方式，这些始终被视为默认导入。

¥NodeJS-style require() calls are also supported. Due to the way require() works, these are always treated as default imports.

1
// Dynamic `require()` call
2
const defaultExport = require('default-import');

选项

¥Options

1
{
2
    "noRestrictedImports": {
3
        "options": {
4
            "paths": {
5
                "lodash": "Using lodash is not encouraged",
6
                "underscore": "Using underscore is not encouraged"
7
            }
8
        }
9
    }
10
}

使用以下选项指定要在源代码中限制的导入路径和/或模式（包括特定的导入名称）。

¥Use the options to specify import paths and/or patterns, including specific import names, that you want to restrict in your source code.

1
{
2
  "linter": {
3
    "rules": {
4
      "style": {
5
        "noRestrictedImports": {
6
          "options": {
7
            "paths": {
8
              "lodash": "Using lodash is not encouraged",
9
              "underscore": "Using underscore is not encouraged",
10
              "import-foo": {
11
                "importNames": [
12
                  "Bar"
13
                ],
14
                "message": "Please use Bar from /import-bar/baz/ instead."
15
              },
16
              "import-bar": {
17
                "allowImportNames": [
18
                  "Bar"
19
                ],
20
                "message": "Please use only Bar from import-bar."
21
              }
22
            }
23
          }
24
        }
25
      }
26
    }
27
  }
28
}

1
{
2
  "linter": {
3
    "rules": {
4
      "style": {
5
        "noRestrictedImports": {
6
          "options": {
7
            "patterns": [
8
              {
9
                "group": [
10
                  "import-foo/*",
11
                  "!import-foo/bar"
12
                ]
13
              }
14
            ]
15
          }
16
        }
17
      }
18
    }
19
  }
20
}

`paths`

列出全部或部分受限的导入路径的对象。

¥An object that lists the import paths that are either wholly or partially restricted.

对象的键是要限制的导入路径，值可以是：

¥The keys of the object are the import paths to restrict, and the values can be:

当出现任何错误时，要在诊断中显示的自定义消息字符串。

¥A string with a custom message to show in the diagnostic when any
具有附加选项的对象，如 below 中所述。

¥An object with additional options, as explained below.

在下面的示例中，我们使用两条特定的消息限制了路径 services-deprecated 和 constants。导入 services-deprecated 将发出消息 Use services instead.。导入 constants 将发出消息 This file will be deleted soon.：

¥In the example below, we restrict the two paths services-deprecated and constants, with two particular messages. Importing services-deprecated will emit the message Use services instead.. Importing constants will emit the message This file will be deleted soon.:

1
{
2
  "linter": {
3
    "rules": {
4
      "style": {
5
        "noRestrictedImports": {
6
          "options": {
7
            "paths": {
8
              "services-deprecated": {
9
                "message": "Use services instead."
10
              },
11
              "constants": "This file will be deleted soon."
12
            }
13
          }
14
        }
15
      }
16
    }
17
  }
18
}

1
import * as namespaceAlias from 'services-deprecated';

code-block.js:1:33 lint/style/noRestrictedImports ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ⚠ Use services instead.
  
  > 1 │ import * as namespaceAlias from ‘services-deprecated’;
      │                                 ^^^^^^^^^^^^^^^^^^^^^
    2 │

1
import { export1 } from 'constants';

code-block.js:1:25 lint/style/noRestrictedImports ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ⚠ This file will be deleted soon.
  
  > 1 │ import { export1 } from ‘constants’;
      │                         ^^^^^^^^^^^
    2 │

`paths.<import>.message`

指定使用受限导入时要显示的消息。

¥Specifies the message to be shown when the restricted import is used.

如果 message 为空或未指定，则会生成默认消息：

¥A default message will be generated if message is empty or not specified:

1
{
2
  "linter": {
3
    "rules": {
4
      "style": {
5
        "noRestrictedImports": {
6
          "options": {
7
            "paths": {
8
              "import-foo": {}
9
            }
10
          }
11
        }
12
      }
13
    }
14
  }
15
}

1
import { export1 } from 'import-foo';

code-block.js:1:25 lint/style/noRestrictedImports ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ⚠ Do not import ‘import-foo’.
  
  > 1 │ import { export1 } from ‘import-foo’;
      │                         ^^^^^^^^^^^^
    2 │

`paths.<import>.importNames`

指定应明确禁止的导入名称数组。支持以下导入名称说明符：

¥Specifies the array of import names that should be explicitly forbidden. The following import name specifiers are supported:

命名导入："someIdentifier"(import { someIdentifier } from 'named-import')

¥Named import: "someIdentifier" (import { someIdentifier } from 'named-import')
默认导入："default"(import defaultExport from 'default-import')

¥Default import: "default" (import defaultExport from 'default-import')
命名空间导入："*"(import * as alias1 from 'namespace-import')

¥Namespace import: "*" (import * as alias1 from 'namespace-import')
副作用/裸导入：""(import "sideeffect-import")

¥Side effect/Bare import: "" (import "sideeffect-import")

必须指定 importNames 和 allowImportNames 中的一个。

¥Only one of importNames and allowImportNames must be specified.

1
{
2
  "linter": {
3
    "rules": {
4
      "style": {
5
        "noRestrictedImports": {
6
          "options": {
7
            "paths": {
8
              "import-foo": {
9
                "importNames": [
10
                  "Bar"
11
                ],
12
                "message": "Please use Bar from /import-bar/baz/ instead."
13
              }
14
            }
15
          }
16
        }
17
      }
18
    }
19
  }
20
}

无效

¥Invalid

1
import { Bar } from 'import-foo';

code-block.js:1:10 lint/style/noRestrictedImports ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ⚠ Please use Bar from /import-bar/baz/ instead.
  
  > 1 │ import { Bar } from ‘import-foo’;
      │          ^^^
    2 │

有效

¥Valid

1
import { Foo } from 'import-foo';

`paths.<import>.allowImportNames`

指定应显式允许的导入名称集合。请参阅 importNames 获取支持的导入名称说明符集。

¥Specifies the set of import names that should be explicitly allowed. See importNames for the set of supported import name specifiers.

必须指定 importNames 和 allowImportNames 中的一个。

¥Only one of importNames and allowImportNames must be specified.

1
{
2
  "linter": {
3
    "rules": {
4
      "style": {
5
        "noRestrictedImports": {
6
          "options": {
7
            "paths": {
8
              "import-bar": {
9
                "allowImportNames": [
10
                  "Bar"
11
                ]
12
              },
13
              "restrictPackagePrivate": "all"
14
            }
15
          }
16
        }
17
      }
18
    }
19
  }
20
}

无效

¥Invalid

1
import { Baz } from 'import-bar';

code-block.js:1:10 lint/style/noRestrictedImports ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ⚠ Do not import ‘Baz’ from ‘import-bar’.
  
  > 1 │ import { Baz } from ‘import-bar’;
      │          ^^^
    2 │ 
  
  ℹ Only the following imports from ‘import-bar’ are allowed:
  
  - Bar

有效

¥Valid

1
import { Bar } from 'import-bar';

`patterns`

自 v2.2.0 版本起：

¥Since v2.2.0

此选项允许你指定多个模块，并使用类似 .gitignore 的模式进行限制。

¥This option allows you to specify multiple modules to restrict using gitignore-style patterns.

`group`

模式数组还可以包含对象。group 属性用于指定类似 .gitignore 的模块限制模式，message 属性用于指定自定义消息。

¥The patterns array can also include objects. The group property is used to specify the gitignore-style patterns for restricting modules and the message property is used to specify a custom message.

1
{
2
  "linter": {
3
    "rules": {
4
      "style": {
5
        "noRestrictedImports": {
6
          "options": {
7
            "patterns": [
8
              {
9
                "group": [
10
                  "import-foo/*",
11
                  "!import-foo/bar"
12
                ],
13
                "message": "import-foo is deprecated, except the modules in import-foo/bar."
14
              }
15
            ]
16
          }
17
        }
18
      }
19
    }
20
  }
21
}

无效

¥Invalid

1
import foo from 'import-foo/foo';

code-block.js:1:17 lint/style/noRestrictedImports ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ⚠ import-foo is deprecated, except the modules in import-foo/bar.
  
  > 1 │ import foo from ‘import-foo/foo’;
      │                 ^^^^^^^^^^^^^^^^
    2 │

有效

¥Valid

1
import foo from 'import-foo';
2
import bar from 'import-foo/bar';

`importNamePattern`

自 v2.2.0 版本起：

¥Since v2.2.0

此选项允许你使用正则表达式模式来限制导入名称。

¥This option allows you to use regex patterns to restrict import names.

1
{
2
  "linter": {
3
    "rules": {
4
      "style": {
5
        "noRestrictedImports": {
6
          "options": {
7
            "patterns": [
8
              {
9
                "group": [
10
                  "import-foo/*"
11
                ],
12
                "importNamePattern": "[xyz]"
13
              }
14
            ]
15
          }
16
        }
17
      }
18
    }
19
  }
20
}

无效

¥Invalid

1
import { x } from 'import-foo/foo';

code-block.js:1:10 lint/style/noRestrictedImports ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ⚠ Do not import ‘x’ from ‘import-foo/foo’.
  
  > 1 │ import { x } from ‘import-foo/foo’;
      │          ^
    2 │

有效

¥Valid

1
import { foo } from 'import-foo/foo';

`invertImportNamePattern`

自 v2.2.0 版本起：

¥Since v2.2.0

如果为真，则允许导入名称模式 (importNamePattern) 中匹配的模式。

¥If true, the matched patterns in the importNamePattern will be allowed

1
{
2
  "linter": {
3
    "rules": {
4
      "style": {
5
        "noRestrictedImports": {
6
          "options": {
7
            "patterns": [
8
              {
9
                "group": [
10
                  "import-foo/*"
11
                ],
12
                "importNamePattern": "[xyz]",
13
                "invertImportNamePattern": true
14
              }
15
            ]
16
          }
17
        }
18
      }
19
    }
20
  }
21
}

无效

¥Invalid

1
import { foo } from 'import-foo/foo';

code-block.js:1:10 lint/style/noRestrictedImports ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ⚠ Do not import ‘foo’ from ‘import-foo/foo’.
  
  > 1 │ import { foo } from ‘import-foo/foo’;
      │          ^^^
    2 │

有效

¥Valid

1
import { x } from 'import-foo/foo';

noRestrictedImports

摘要

如何配置

描述

示例

无效

有效

支持的导入语法

静态 import（和 re-export）声明

动态 import() 调用

动态 require() 调用

选项

paths

paths.<import>.message

paths.<import>.importNames

无效

有效

paths.<import>.allowImportNames

无效

有效

patterns

group

无效

有效

importNamePattern

无效

有效

invertImportNamePattern

无效

有效

相关链接

静态 `import`（和 re-`export`）声明

动态 `import()` 调用

动态 `require()` 调用

`paths`

`paths.<import>.message`

`paths.<import>.importNames`

`paths.<import>.allowImportNames`

`patterns`

`group`

`importNamePattern`

`invertImportNamePattern`