no-restricted-imports

當使用 import 載入時，不允許指定的模組

Imports 是 ES6/ES2015 標準，用於使其他模組的功能在您目前的模組中可用。在 CommonJS 中，這是透過 require() 呼叫實作的，這使得此 ESLint 規則大致等同於其 CommonJS 對應規則 no-restricted-modules。

為什麼您會想要限制 imports？

• 某些 imports 在特定環境中可能沒有意義。例如，Node.js 的 fs 模組在沒有檔案系統的環境中就沒有意義。

• 有些模組提供相似或相同的功能，想想 lodash 和 underscore。您的專案可能已標準化一個模組。您想要確保不使用其他替代方案，因為這會不必要地膨脹專案，並在一個依賴項就足夠的情況下，提供更高的兩個依賴項的維護成本。

規則詳情

此規則允許您指定您不想在應用程式中使用的 imports。

它僅適用於靜態 imports，不適用於動態 imports。

選項

此規則同時具有字串和物件選項，用於指定要限制的匯入模組。

使用字串選項，您可以指定您想要限制匯入的模組名稱，作為規則選項陣列中的值

"no-restricted-imports": ["error", "import1", "import2"]
1

字串選項的錯誤程式碼範例

/*eslint no-restricted-imports: ["error", "fs"]*/

import fs from 'fs';
1
2
3

字串選項也限制模組被匯出，如此範例所示

/*eslint no-restricted-imports: ["error", "fs"]*/

export { fs } from 'fs';
1
2
3

/*eslint no-restricted-imports: ["error", "fs"]*/

export * from 'fs';
1
2
3

字串選項的正確程式碼範例

/*eslint no-restricted-imports: ["error", "fs"]*/

import crypto from 'crypto';
export { foo } from "bar";
1
2
3
4

您也可以使用物件內部的 name 和 message 屬性，為特定模組指定自訂訊息，其中 name 的值是模組的名稱，而 message 屬性包含自訂訊息。（自訂訊息會附加到規則的預設錯誤訊息。）

"no-restricted-imports": ["error", {
    "name": "import-foo",
    "message": "Please use import-bar instead."
}, {
    "name": "import-baz",
    "message": "Please use import-quux instead."
}]
1
2
3
4
5
6
7

字串選項的錯誤程式碼範例

/*eslint no-restricted-imports: ["error", {
    "name": "disallowed-import",
    "message": "Please use 'allowed-import' instead"
}]*/

import foo from 'disallowed-import';
1
2
3
4
5
6

paths

這是一個物件選項，其值是一個陣列，其中包含您想要限制的模組名稱。

"no-restricted-imports": ["error", { "paths": ["import1", "import2"] }]
1

paths 的錯誤程式碼範例

/*eslint no-restricted-imports: ["error", { "paths": ["cluster"] }]*/

import cluster from 'cluster';
1
2
3

特定模組的自訂訊息也可以在使用具有 name 和 message 的物件的 paths 陣列中指定。

"no-restricted-imports": ["error", {
    "paths": [{
        "name": "import-foo",
        "message": "Please use import-bar instead."
    }, {
        "name": "import-baz",
        "message": "Please use import-quux instead."
    }]
}]
1
2
3
4
5
6
7
8
9

importNames

paths 中的此選項是一個陣列，可用於指定從模組匯出的某些綁定名稱。在 paths 陣列內指定的匯入名稱會影響對應物件的 name 屬性中指定的模組，因此當您使用 importNames 或 message 選項時，必須先指定 name 屬性。

在 importNames 陣列內指定 "default" 字串將會限制從預設匯出中匯入。

"no-restricted-imports": ["error", {
  "paths": [{
    "name": "import-foo",
    "importNames": ["Bar"],
    "message": "Please use Bar from /import-bar/baz/ instead."
  }]
}]
1
2
3
4
5
6
7

當 paths 中的 importNames 具有 "default" 時的錯誤程式碼範例

/*eslint no-restricted-imports: ["error", { paths: [{
    name: "foo",
    importNames: ["default"],
    message: "Please use the default import from '/bar/baz/' instead."
}]}]*/

import DisallowedObject from "foo";
1
2
3
4
5
6
7

paths 中 importNames 的錯誤程式碼範例

/*eslint no-restricted-imports: ["error", { paths: [{
    name: "foo",
    importNames: ["DisallowedObject"],
    message: "Please import 'DisallowedObject' from '/bar/baz/' instead."
}]}]*/

import { DisallowedObject } from "foo";

import { DisallowedObject as AllowedObject } from "foo";

import { "DisallowedObject" as SomeObject } from "foo";
1
2
3
4
5
6
7
8
9
10
11

/*eslint no-restricted-imports: ["error", { paths: [{
    name: "foo",
    importNames: ["DisallowedObject"],
    message: "Please import 'DisallowedObject' from '/bar/baz/' instead."
}]}]*/

import * as Foo from "foo";
1
2
3
4
5
6
7

paths 中 importNames 的正確程式碼範例

如果指派給預設匯出的本地名稱與 importNames 中的字串相同，則不會導致錯誤。

/*eslint no-restricted-imports: ["error", { paths: [{ name: "foo", importNames: ["DisallowedObject"] }] }]*/

import DisallowedObject from "foo"
1
2
3

/*eslint no-restricted-imports: ["error", { paths: [{
    name: "foo",
    importNames: ["DisallowedObject"],
    message: "Please import 'DisallowedObject' from '/bar/baz/' instead."
}]}]*/

import { AllowedObject as DisallowedObject } from "foo";
1
2
3
4
5
6
7

allowImportNames

此選項是一個陣列。allowImportNames 是 importNames 的反向，允許在此陣列中指定的匯入。因此，它會限制來自模組的所有匯入，除了指定的允許匯入。

注意：allowImportNames 無法與 importNames 組合使用。

"no-restricted-imports": ["error", {
  "paths": [{
    "name": "import-foo",
    "allowImportNames": ["Bar"],
    "message": "Please use only Bar from import-foo."
  }]
}]
1
2
3
4
5
6
7

paths 中 allowImportNames 的錯誤程式碼範例

不允許除了 'AllowedObject' 之外的所有匯入名稱。

/*eslint no-restricted-imports: ["error", { paths: [{
    name: "foo",
    allowImportNames: ["AllowedObject"],
    message: "Please use only 'AllowedObject' from 'foo'."
}]}]*/

import { DisallowedObject } from "foo";
1
2
3
4
5
6
7

paths 中 allowImportNames 的正確程式碼範例

不允許除了 'AllowedObject' 之外的所有匯入名稱。

/*eslint no-restricted-imports: ["error", { paths: [{
    name: "foo",
    allowImportNames: ["AllowedObject"],
    message: "Only use 'AllowedObject' from 'foo'."
}]}]*/

import { AllowedObject } from "foo";
1
2
3
4
5
6
7

patterns

這也是一個物件選項，其值是一個陣列。此選項允許您使用 gitignore 樣式的模式或正則表達式來指定要限制的多個模組。

paths 選項採用確切的匯入路徑，而 patterns 選項可以用於更彈性地指定匯入路徑，允許限制同一目錄中的多個模組。例如

"no-restricted-imports": ["error", {
  "paths": [{
    "name": "import-foo",
  }]
}]
1
2
3
4
5

此設定限制匯入 import-foo 模組，但不限制匯入 import-foo/bar 或 import-foo/baz。您可以使用 patterns 來限制兩者

"no-restricted-imports": ["error", {
    "paths": [{
      "name": "import-foo",
    }],
    "patterns": [{
      "group": ["import-foo/ba*"],
    }]
}]
1
2
3
4
5
6
7
8

此設定不僅使用 path 限制來自 import-foo 的匯入，還使用 patterns 限制來自 import-foo/bar 和 import-foo/baz 的匯入。

若要在使用 gitignore- 樣式模式時重新包含模組，請在模式前新增否定 (!) 標記。（請確保這些否定模式放在陣列的最後，因為順序很重要）

"no-restricted-imports": ["error", {
    "patterns": ["import1/private/*", "import2/*", "!import2/good"]
}]
1
2
3

您也可以使用正則表達式來限制模組（請參閱 regex 選項）。

patterns 選項的錯誤程式碼範例

/*eslint no-restricted-imports: ["error", { "patterns": ["lodash/*"] }]*/

import pick from 'lodash/pick';
1
2
3

/*eslint no-restricted-imports: ["error", { "patterns": ["lodash/*", "!lodash/pick"] }]*/

import pick from 'lodash/map';
1
2
3

/*eslint no-restricted-imports: ["error", { "patterns": ["import1/*", "!import1/private/*"] }]*/

import pick from 'import1/private/someModule';
1
2
3

在此範例中，"!import1/private/*" 並未重新包含 private 內部的模組，因為如果否定標記 (!) 的父目錄被模式排除，則否定標記不會重新包含檔案。在此情況下，import1/private 目錄已由 import1/* 模式排除。（可以使用 "!import1/private" 重新包含排除的目錄。）

patterns 選項的正確程式碼範例

/*eslint no-restricted-imports: ["error", { "patterns": ["crypto/*"] }]*/

import crypto from 'crypto';
1
2
3

/*eslint no-restricted-imports: ["error", { "patterns": ["lodash/*", "!lodash/pick"] }]*/

import pick from 'lodash/pick';
1
2
3

/*eslint no-restricted-imports: ["error", { "patterns": ["import1/*", "!import1/private"] }]*/

import pick from 'import1/private/someModule';
1
2
3

group

patterns 陣列也可以包含物件。group 屬性用於指定用於限制模組的 gitignore 樣式模式，而 message 屬性用於指定自訂訊息。

當使用 patterns 選項時，group 或 regex 屬性兩者之一是必要的。

"no-restricted-imports": ["error", {
    "patterns": [{
      "group": ["import1/private/*"],
      "message": "usage of import1 private modules not allowed."
    }, {
      "group": ["import2/*", "!import2/good"],
      "message": "import2 is deprecated, except the modules in import2/good."
    }]
}]
1
2
3
4
5
6
7
8
9

group 選項的錯誤程式碼範例

/*eslint no-restricted-imports: ["error", { patterns: [{
    group: ["lodash/*"],
    message: "Please use the default import from 'lodash' instead."
}]}]*/

import pick from 'lodash/pick';
1
2
3
4
5
6

此 group 選項的正確程式碼範例

/*eslint no-restricted-imports: ["error", { patterns: [{
    group: ["lodash/*"],
    message: "Please use the default import from 'lodash' instead."
}]}]*/

import lodash from 'lodash';
1
2
3
4
5
6

regex

regex 屬性用於指定用於限制模組的正則表達式模式。

注意：regex 無法與 group 組合使用。

"no-restricted-imports": ["error", {
    "patterns": [{
      "regex": "import1/private/",
      "message": "usage of import1 private modules not allowed."
    }, {
      "regex": "import2/(?!good)",
      "message": "import2 is deprecated, except the modules in import2/good."
    }]
}]
1
2
3
4
5
6
7
8
9

regex 選項的錯誤程式碼範例

/*eslint no-restricted-imports: ["error", { patterns: [{
    regex: "@app/(?!(api/enums$)).*",
}]}]*/

import Foo from '@app/api';
import Bar from '@app/api/bar';
import Baz from '@app/api/baz';
import Bux from '@app/api/enums/foo';
1
2
3
4
5
6
7
8

regex 選項的正確程式碼範例

/*eslint no-restricted-imports: ["error", { patterns: [{
    regex: "@app/(?!(api/enums$)).*",
}]}]*/

import Foo from '@app/api/enums';
1
2
3
4
5

caseSensitive

這是一個布林值選項，當為 true 時，會將 group 或 regex 屬性中指定的模式設定為區分大小寫。預設值為 false。

"no-restricted-imports": ["error", {
    "patterns": [{
      "group": ["import1/private/prefix[A-Z]*"],
      "caseSensitive": true
    }]
}]
1
2
3
4
5
6

caseSensitive: true 選項的錯誤程式碼範例

/*eslint no-restricted-imports: ["error", { patterns: [{
    group: ["foo[A-Z]*"],
    caseSensitive: true
}]}]*/

import pick from 'fooBar';
1
2
3
4
5
6

caseSensitive: true 選項的正確程式碼範例

/*eslint no-restricted-imports: ["error", { patterns: [{
    group: ["foo[A-Z]*"],
    caseSensitive: true
}]}]*/

import pick from 'food';
1
2
3
4
5
6

importNames

您也可以在 patterns 陣列內部的物件中指定 importNames。在這種情況下，指定的名稱僅適用於相關聯的 group 或 regex 屬性。

"no-restricted-imports": ["error", {
    "patterns": [{
      "group": ["utils/*"],
      "importNames": ["isEmpty"],
      "message": "Use 'isEmpty' from lodash instead."
    }]
}]
1
2
3
4
5
6
7

patterns 中 importNames 的錯誤程式碼範例

/*eslint no-restricted-imports: ["error", { patterns: [{
    group: ["utils/*"],
    importNames: ['isEmpty'],
    message: "Use 'isEmpty' from lodash instead."
}]}]*/

import { isEmpty } from 'utils/collection-utils';
1
2
3
4
5
6
7

patterns 中 importNames 的正確程式碼範例

/*eslint no-restricted-imports: ["error", { patterns: [{
    group: ["utils/*"],
    importNames: ['isEmpty'],
    message: "Use 'isEmpty' from lodash instead."
}]}]*/

import { hasValues } from 'utils/collection-utils';
1
2
3
4
5
6
7

allowImportNames

您也可以在 patterns 陣列內部的物件中指定 allowImportNames。在這種情況下，指定的名稱僅適用於相關聯的 group 或 regex 屬性。

注意：allowImportNames 無法與 importNames、importNamePattern 或 allowImportNamePattern 組合使用。

"no-restricted-imports": ["error", {
    "patterns": [{
      "group": ["utils/*"],
      "allowImportNames": ["isEmpty"],
      "message": "Please use only 'isEmpty' from utils."
    }]
}]
1
2
3
4
5
6
7

patterns 中 allowImportNames 的錯誤程式碼範例

/*eslint no-restricted-imports: ["error", { patterns: [{
    group: ["utils/*"],
    allowImportNames: ['isEmpty'],
    message: "Please use only 'isEmpty' from utils."
}]}]*/

import { hasValues } from 'utils/collection-utils';
1
2
3
4
5
6
7

patterns 中 allowImportNames 的正確程式碼範例

/*eslint no-restricted-imports: ["error", { patterns: [{
    group: ["utils/*"],
    allowImportNames: ['isEmpty'],
    message: "Please use only 'isEmpty' from utils."
}]}]*/

import { isEmpty } from 'utils/collection-utils';
1
2
3
4
5
6
7

importNamePattern

此選項允許您使用正則表達式模式來限制匯入名稱

"no-restricted-imports": ["error", {
    "patterns": [{
      "group": ["import-foo/*"],
      "importNamePattern": "^foo",
    }]
}]
1
2
3
4
5
6

importNamePattern 選項的錯誤程式碼範例

/*eslint no-restricted-imports: ["error", { patterns: [{
    group: ["utils/*"],
    importNamePattern: '^is',
    message: "Use 'is*' functions from lodash instead."
}]}]*/

import { isEmpty } from 'utils/collection-utils';
1
2
3
4
5
6
7

/*eslint no-restricted-imports: ["error", { patterns: [{
    group: ["foo/*"],
    importNamePattern: '^(is|has)',
    message: "Use 'is*' and 'has*' functions from baz/bar instead"
}]}]*/

import { isSomething, hasSomething } from 'foo/bar';
1
2
3
4
5
6
7

/*eslint no-restricted-imports: ["error", { patterns: [{
    group: ["foo/*"],
    importNames: ["bar"],
    importNamePattern: '^baz',
}]}]*/

import { bar, bazQux } from 'foo/quux';
1
2
3
4
5
6
7

importNamePattern 選項的正確程式碼範例

/*eslint no-restricted-imports: ["error", { patterns: [{
    group: ["utils/*"],
    importNamePattern: '^is',
    message: "Use 'is*' functions from lodash instead."
}]}]*/

import isEmpty, { hasValue } from 'utils/collection-utils';
1
2
3
4
5
6
7

您也可以使用此選項僅允許副作用匯入，方法是將其設定為符合任何名稱的模式，例如 ^。

importNamePattern 選項的錯誤程式碼範例

/*eslint no-restricted-imports: ["error", { patterns: [{
    group: ["utils/*"],
    importNamePattern: "^"
}]}]*/

import isEmpty, { hasValue } from 'utils/collection-utils';

import * as file from 'utils/file-utils';
1
2
3
4
5
6
7
8

importNamePattern 選項的正確程式碼範例

/*eslint no-restricted-imports: ["error", { patterns: [{
    group: ["utils/*"],
    importNamePattern: "^"
}]}]*/

import 'utils/init-utils';
1
2
3
4
5
6

allowImportNamePattern

這是一個字串選項。allowImportNamePattern 是 importNamePattern 的反向，此選項允許符合指定正則表達式模式的匯入。因此，它會限制來自模組的所有匯入，除了指定的允許模式。

注意：allowImportNamePattern 無法與 importNames、importNamePattern 或 allowImportNames 組合使用。

"no-restricted-imports": ["error", {
    "patterns": [{
      "group": ["import-foo/*"],
      "allowImportNamePattern": "^foo",
    }]
}]
1
2
3
4
5
6

allowImportNamePattern 選項的錯誤程式碼範例

/*eslint no-restricted-imports: ["error", { patterns: [{
    group: ["utils/*"],
    allowImportNamePattern: '^has'
}]}]*/

import { isEmpty } from 'utils/collection-utils';
1
2
3
4
5
6

allowImportNamePattern 選項的正確程式碼範例

/*eslint no-restricted-imports: ["error", { patterns: [{
    group: ["utils/*"],
    allowImportNamePattern: '^is'
}]}]*/

import { isEmpty } from 'utils/collection-utils';
1
2
3
4
5
6

何時不該使用

如果您希望能夠在您的專案中匯入模組而沒有 ESLint 錯誤或警告，請勿使用此規則，或不要在此規則的清單中包含模組。

版本

此規則在 ESLint v2.0.0-alpha-1 中引入。

資源

• 規則來源
• 測試來源