organizeImports

JavaScript (i języki nadrzędne)

Podsumowanie

Reguła dostępna od: v1.0.0
Kategoria diagnostyczna: assist/source/organizeImports
Ta akcja jest zalecana.
Domyślna ważność tej reguły to information.

Jak włączyć w edytorze

1
{
2
  "editor.codeActionsOnSave": {
3
    "source.organizeImports.biome": "explicit",
4
    "source.fixAll.biome": "explicit"
5
  }
6
}

1
{
2
  "code_actions_on_format": {
3
    "source.organizeImports.biome": true,
4
    "source.fixAll.biome": true
5
  }
6
}

Use the source action code source.organizeImports.biome

Jak skonfigurować

1
{
2
  "assist": {
3
    "actions": {
4
      "source": {
5
        "organizeImports": "on"
6
      }
7
    }
8
  }
9
}

Opis

Dostarcza akcję kodu do sortowania importów i eksportów w pliku przy użyciu wbudowanego lub niestandardowego porządku.

Importy i eksporty są najpierw rozdzielane na fragmenty, a następnie sortowane. Importy lub eksporty fragmentu są następnie grupowane zgodnie z grupami zdefiniowanymi przez użytkownika. W obrębie grupy importy są sortowane przy użyciu wbudowanego porządku, który zależy od rodzaju importu/eksportu, czy import/eksport ma atrybuty i źródła, z którego jest importowany. source jest również często nazywany specifier w ekosystemie JavaScript.

1
import A from "@my/lib" with { "attribute1": "value" };
2
^^^^^^^^       ^^^^^^^         ^^^^^^^^^^^^^^^^^^^^^
3
  kind         source                attributes
4

5
export * from "@my/lib" with { "attribute1": "value" };
6
^^^^^^^^       ^^^^^^^         ^^^^^^^^^^^^^^^^^^^^^
7
  kind         source                attributes

Fragment importów i fragment eksportów

Fragment to sekwencja sąsiadujących importów lub eksportów. Fragment zawiera tylko importy lub eksporty, nie oba jednocześnie. Poniższy przykład zawiera dwa fragmenty. Pierwszy fragment składa się z trzech importów, a drugi fragment składa się z trzech eksportów.

1
// fragment 1
2
import A from "a";
3
import * as B from "b";
4
import { C } from "c";
5
// fragment 2
6
export * from "d";
7
export * as F from "e";
8
export { F } from "f";

Fragmenty kończą się również zaraz po napotkaniu instrukcji lub importu efektu ubocznego (zwanego również bare import). Każdy import efektu ubocznego tworzy niezależny fragment. Poniższy przykład zawiera sześć fragmentów:

1
// fragment 1
2
import A from "a";
3
import * as B from "b";
4
// fragment 2
5
import "x";
6
// fragment 3
7
import "y";
8
// fragment 4
9
import { C } from "c";
10
// fragment 5
11
export * from "d";
12
function f() {}
13
// fragment 6
14
export * as E from "e";
15
export { F } from "f";

Pierwszy fragment zawiera dwa pierwsze import i kończy się pojawieniem się pierwszego importu efektu ubocznego import "x".
Drugi fragment zawiera tylko import efektu ubocznego import "x".
Trzeci fragment zawiera tylko import efektu ubocznego import "y".
Czwarty fragment zawiera pojedynczy import; Pierwszy export go kończy.
Piąty fragment zawiera pierwszy export; Deklaracja funkcji go kończy.
Szósty fragment zawiera ostatnie dwa export.

Fragmenty są również ograniczone przez odłączone komentarze. Odłączony komentarz to komentarz po którym następuje pusta linia. Komentarze nie poprzedzone pustą linią to dołączone komentarze. Należy zauważyć, że same puste linie nie są brane pod uwagę przy dzieleniu importów i eksportów na fragmenty. Poniższy przykład zawiera odłączony komentarz, który dzieli importy na dwa fragmenty:

1
// Dołączony komentarz 1
2
import A from "a";
3

4
// Dołączony komentarz 2
5
import * as B from "b";
6
// Odłączony komentarz
7

8
import { C } from "c";

Linia import { C } from "c" tworzy drugi fragment. Pusta linia między pierwszymi dwoma importami jest ignorowana, więc tworzą one pojedynczy fragment.

Sortownik zapewnia, że fragmenty są oddzielone od siebie pustymi liniami. Tylko importy efektu ubocznego sąsiadujące z fragmentem importów nie są oddzielone pustą linią. Poniższy kod…

1
import A from "a";
2
import * as B from "b";
3
import "x";
4
import { C } from "c";
5
export * from "d";
6
// Odłączony komentarz
7

8
export * as F from "e";
9
// Dołączony komentarz
10
export { F } from "f";

jest sortowany jako:

1
import A from "a";
2
import * as B from "b";
3
import "x";
4
import { C } from "c";
5

6
export * from "d";
7

8
// Odłączony komentarz
9

10
export * as F from "e";
11
// Dołączony komentarz
12
export { F } from "f";

Należy również zauważyć, że puste linie wewnątrz fragmentu są ignorowane i zachowywane. Mogą być usunięte przez jawne zdefiniowanie grup, jak pokazano w następnej sekcji.

Sortowanie importów i eksportów

Po utworzeniu fragmentów, importy i eksporty każdego fragmentu są sortowane. Importy i eksporty są sortowane według ich źródła. Źródła są uporządkowane według “odległości”. Źródła “dalsze” od bieżącego modułu są umieszczane na górze, źródła “bliższe” użytkownikowi są umieszczane na dole. Prowadzi to do następującego porządku:

URL-e takie jak https://example.org.
Pakiety z protokołem takim jak node:path, bun:test, jsr:@my?lib, lub npm:lib.
Pakiety takie jak mylib lub @my/lib.
Aliasy: źródła zaczynające się od @/, #, ~, $, lub %. Zwykle są to Node.js subpath imports lub TypeScript path aliases.
Ścieżki bezwzględne i względne.

Dwa importy/eksporty z tą samą kategorią źródła są sortowane przy użyciu natural sort order dostosowanego do URL-i, pakietów i ścieżek. W szczególności, porządek zapewnia, że A < a < B < b. Porządek uwzględnia również liczby, np. a9 < a10.

Na przykład, następujący kod…

1
import sibling from "./file.js";
2
import internal from "#alias";
3
import fs from "fs";
4
import { test } from "node:test";
5
import path from "node:path";m
6
```js
7
import data from "https://example.org";
8
import scopedLibUsingJsr from "jsr:@scoped/lib";
9
import path from "node:path";
10
import { test } from "node:test";
11
import scopedLib from "@scoped/lib";
12
import fs from "fs";
13
import lib from "lib";
14
import internal from "#alias";
15
import parent from "../parent.js";
16
import sibling from "./file.js";

Jeśli dwa importy lub eksporty mają to samo źródło i są w tym samym fragmencie, są one uporządkowane według ich rodzaju następująco:

Import/eksport typu namespace
Import typu default
Import/eksport typu named
Import/eksport namespace
Kombinowany import default i namespace
Import default
Kombinowany import default i named
Import/eksport named

Importy i eksporty z atrybutami są zawsze umieszczane na początku. Na przykład, następujący kod…

1
import * as namespaceImport from "same-source";
2
import type * as namespaceTypeImport from "same-source";
3
import type { namedTypeImport } from "same-source";
4
import defaultNamespaceCombined, * as namespaceCombined from "same-source";
5
import defaultNamedCombined, { namedCombined } from "same-source";
6
import defaultImport from "same-source";
7
import type defaultTypeImport from "same-source";
8
import { importWithAttribute } from "same-source" with { "attribute": "value" } ;

jest sortowany następująco:

1
import { importWithAttribute } from "same-source" with { "attribute": "value" } ;
2
import type * as namespaceTypeImport from "same-source";
3
import type defaultTypeImport from "same-source";
4
import type { namedTypeImport } from "same-source";
5
import * as namespaceImport from "same-source";
6
import defaultNamespaceCombined, * as namespaceCombined from "same-source";
7
import defaultImport from "same-source";
8
import defaultNamedCombined, { namedCombined } from "same-source";

Ten domyślny porządek nie może być zmieniony. Jednak użytkownicy mogą nadal dostosować sposób sortowania importów i eksportów używając koncepcji grup, jak wyjaśniono w następnej sekcji.

Grupy importów i eksportów

Importy lub eksporty fragmentu są dzielone na grupy przed sortowaniem przy użyciu wbudowanego porządku opisanego w poprzedniej sekcji. Domyślnie każdy fragment składa się z pojedynczej grupy. Te domyślne grupy i ich porządek mogą nie odpowiadać Twoim preferencjom. Sortownik dostarcza opcję groups, która pozwala dostosować sposób dzielenia fragmentów na grupy. Opcja groups to lista dopasowań grup. Dopasowanie grupy to:

Wstępnie zdefiniowane dopasowanie grupy, lub
Wzorzec glob, lub
Dopasowanie obiektu, lub
Lista wzorców glob, wstępnie zdefiniowanych dopasowań grup i dopasowań obiektów.

Wstępnie zdefiniowane dopasowania grup to ciągi znaków w CONSTANT_CASE poprzedzone i zakończone przez :. Sortownik dostarcza kilka wstępnie zdefiniowanych dopasowań grup:

:ALIAS:: źródła zaczynające się od #, @/, ~, $, lub %.
:BUN:: źródła zaczynające się od protokołu bun: lub odpowiadające wbudowanemu modułowi Bun takiemu jak bun.
:NODE:: źródła zaczynające się od protokołu node: lub odpowiadające wbudowanemu modułowi Node.js takiemu jak fs lub path.
:PACKAGE:: pakiety scoped i bare.
:PACKAGE_WITH_PROTOCOL:: pakiety scoped i bare z protokołem.
:PATH:: ścieżki bezwzględne i względne.
:URL:: źródła zaczynające się od https:// i http://.

Weźmy przykład. W domyślnej konfiguracji, moduły Node.js bez protokołu node: są oddzielone od tych z protokołem. Aby pogrupować je razem, możesz użyć wstępnie zdefiniowanej grupy :NODE:. Przy danej konfiguracji…

1
{
2
    "assist": {
3
        "actions": {
4
            "source": {
5
                "organizeImports": {
6
                    "level": "on",
7
                    "options": {
8
                        "groups": [
9
                            ":URL:",
10
                            ":NODE:"
11
                        ]
12
                    }
13
                }
14
            }
15
        }
16
    }
17
}
18
{
19
  "assist": {
20
    "actions": {
21
      "source": {
22
        "organizeImports": {
23
          "level": "on",
24
          "options": {
25
            "groups": [
26
              ":URL:",
27
              ":NODE:"
28
            ]
29
          }
30
        }
31
      }
32
    }
33
  }
34
}

…i następujący kod…

1
import sibling from "./file.js";
2
import internal from "#alias";
3
import fs from "fs";
4
import { test } from "node:test";
5
import path from "node:path";
6
import parent from "../parent.js";
7
import scopedLibUsingJsr from "jsr:@scoped/lib";
8
import data from "https://example.org";
9
import lib from "lib";
10
import scopedLib from "@scoped/lib";

…kończymy z następującym posortowanym wynikiem, gdzie importy node:path i modułu Node.js fs są pogrupowane razem:

1
import data from "https://example.org";
2
import fs from "fs";
3
import path from "node:path";
4
import { test } from "node:test";
5
import scopedLibUsingJsr from "jsr:@scoped/lib";
6
import scopedLib from "@scoped/lib";
7
import lib from "lib";
8
import internal from "#alias";
9
import parent from "../parent.js";
10
import sibling from "./file.js";

Należy zauważyć, że wszystkie importy, które nie pasują do dopasowania grupy, są zawsze umieszczane na końcu.

Dopasowania grup mogą być również wzorcami glob i listami wzorców glob. Wzorce glob wybierają importy i eksporty ze źródłem, które pasuje do wzorca. W następnym przykładzie tworzymy dwie grupy: jedną, która zbiera importy/eksporty ze źródłem zaczynającym się od @my/lib z wyjątkiem @my/lib/special i drugą, która zbiera importy/eksporty zaczynające się od @/.

1
{
2
    "options": {
3
        "groups": [
4
            ["@my/lib", "@my/lib/**", "!@my/lib/special", "!@my/lib/special/**"],
5
            "@/**"
6
        ]
7
    }
8
}

Stosując tę konfigurację do następującego kodu…

1
import lib from "@my/lib";
2
import aliased from "@/alias";
3
import path from "@my/lib/special";
4
import test from "@my/lib/path";

…otrzymujemy następujący posortowany wynik. Importy ze źródłami @my/lib i @my/lib/path tworzą pierwszą grupę. Pasują odpowiednio do wzorców glob @my/lib i @my/lib/**. Import ze źródłem @my/lib/special nie jest umieszczany w tej pierwszej grupie, ponieważ jest odrzucany przez wyjątek !@my/lib/special. Import ze źródłem @/alias jest umieszczany w drugiej grupie, ponieważ pasuje do wzorca glob @/**. W końcu, inne importy są umieszczane na końcu.

1
import lib from "@my/lib";
2
import test from "@my/lib/path";
3
import aliased from "@/alias";
4
import path from "@my/lib/special";

Należy zauważyć, że @my/lib pasuje do @my/lib, ale nie do @my/lib/**. Odwrotnie, @my/lib/subpath pasuje do @my/lib/**, ale nie do @my/lib. Więc musisz określić oba wzorce glob, jeśli chcesz zaakceptować wszystkie importy/eksporty, które zaczynają się od @my/lib. Prefiks ! wskazuje wyjątek. Możesz tworzyć wyjątki wyjątków, następując po wyjątku zwykłym wzorcem glob. Na przykład ["@my/lib", "@my/lib/**", "!@my/lib/special", "!@my/lib/special/**", "@my/lib/special/*/accepted/**"] pozwala zaakceptować wszystkie źródła pasujące do @my/lib/special/*/accepted/**. Należy zauważyć, że wstępnie zdefiniowane grupy mogą być również negowane. !:NODE: pasuje do wszystkich źródeł, które nie pasują do :NODE:. Aby uzyskać więcej szczegółów na temat obsługiwanych wzorców glob, zobacz dedykowaną sekcję.

W końcu, dopasowania grup mogą być dopasowaniami obiektów. Dopasowanie obiektu pozwala dopasować importy i eksporty tylko typu.

Przy danej konfiguracji:

1
{
2
    "options": {
3
        "groups": [
4
            { "type": false, "source": ["@my/lib", "@my/lib/**"] },
5
            ["@my/lib", "@my/lib/**"]
6
        ]
7
    }
8
}

Następujący kod:

1
import type { T } from "@my/lib";
2
import { V } from "@my/lib";

is sorted as follows:

1
import { V } from "@my/lib";
2
import type { T } from "@my/lib";

Dopasowanie obiektu { "type": false, "source": ["@my/lib", "@my/lib/**"] } pasuje do importów i eksportów bez słowa kluczowego type ze źródłem, które pasuje do jednego ze wzorców glob z listy ["@my/lib", "@my/lib/**"].

Sortownik pozwala na oddzielenie dwóch grup pustą linią przy użyciu wstępnie zdefiniowanego ciągu :BLANK_LINE:. Przy danej konfiguracji…

1
{
2
    "options": {
3
        "groups": [
4
            [":BUN:", ":NODE:"],
5
            ":BLANK_LINE:",
6
            ["@my/lib", "@my/lib/**", "!@my/lib/special", "!@my/lib/special/**"],
7
            "@/**"
8
        ]
9
    }
10
}

…następujący kod…

1
import test from "bun:test";
2
import path from "node:path";
3
import lib from "@my/lib";
4
import libPath from "@my/lib/path";
5
import libSpecial from "@my/lib/special";
6
import aliased from "@/alias";

…jest sortowany jako:

1
import path from "node:path";
2

3
import lib from "@my/lib";
4
import test from "@my/lib/path";
5
import aliased from "@/alias";
6
import path from "@my/lib/special";

Grupy są dopasowywane w kolejności. Oznacza to, że jedno dopasowanie grupy może zasłaniać następujące grupy. Na przykład, w następnej konfiguracji, dopasowanie grupy :URL: nigdy nie jest dopasowywane, ponieważ wszystkie importy i eksporty pasują do pierwszego dopasowania **.

1
{
2
    "options": {
3
        "groups": [
4
            "**",
5
            ":URL:"
6
        ]
7
    }
8
}

Obsługa komentarzy

Podczas sortowania importów i eksportów, dołączone komentarze są przenoszone z ich importem lub eksportem, a odłączone komentarze (komentarze po których następuje pusta linia) pozostają na swoim miejscu.

Jednak jest wyjątek od tej reguły. Jeśli komentarz pojawia się na górze pliku, jest uważany za odłączony, nawet jeśli nie następuje po nim pusta linia. To zapewnia, że noty copyright i komentarze nagłówka pliku pozostają na górze pliku.

Na przykład, następujący kod…

1
// Nota copyright i komentarz nagłówka pliku
2
import F from "f";
3
// Dołączony komentarz dla `e`
4
import E from "e";
5
// Dołączony komentarz dla `d`
6
import D from "d";
7
// Odłączony komentarz (nowy fragment)
8

9
// Dołączony komentarz dla `b`
10
import B from "b";
11
// Dołączony komentarz dla `a`
12
import A from "a";

…jest sortowany następująco. Pusta linia jest automatycznie dodawana po komentarzu nagłówka, aby zapewnić, że dołączony komentarz nie łączy się z komentarzem nagłówka.

1
// Nota copyright i komentarz nagłówka pliku
2

3
// Dołączony komentarz dla `d`
4
import D from "d";
5
// Dołączony komentarz dla `e`
6
import E from "e";
7
import F from "f";
8

9
// Odłączony komentarz (nowy fragment)
10

11
// Dołączony komentarz dla `a`
12
import A from "a";
13
// Dołączony komentarz dla `b`
14
import B from "b";

Łączenie importów i eksportów

Organizator również łączy importy i eksporty, które mogą być połączone.

Na przykład, następujący kod:

1
import type { T1 } from "package";
2
import type { T2 } from "package";
3
import * as ns from "package";
4
import D1 from "package";
5
import D2 from "package";
6
import { A } from "package";
7
import { B } from "package";

jest łączony następująco:

1
import type { T1, T2 } from "package";
2
import D1, * as ns from "package";
3
import D2, { A, B } from "package";

Sortowanie named importów, named eksportów i atrybutów

Sortownik również sortuje named importy, named eksporty, a także atrybuty. Używa naturalnego porządku sortowania do porównywania liczb.

Następujący kod…

1
import { a, b, A, B, c10, c9 } from "a";
2

3
export { a, b, A, B, c10, c9 } from "a";
4

5
import special from  "special" with { "type": "ty", "metadata": "data" };

…is sorted as follows:

1
import { A, a, B, b, c9, c10 } from "a";
2

3
export { A, a, B, b, c9, c10 } from "a";
4

5
import special from  "special" with { "metadata": "data", "type": "ty" };

Obsługiwane wzorce glob

Musisz zrozumieć strukturę źródła, aby zrozumieć, które źródło pasuje do wzorca glob. Źródło jest podzielone na segmenty źródła. Każdy segment źródła jest ograniczony separatorem / lub początkiem/końcem źródła. Na przykład src/file.js składa się z dwóch segmentów źródła: src i file.js.

gwiazdka * która pasuje do zera lub więcej znaków wewnątrz segmentu źródła

file.js pasuje do *.js. Odwrotnie, src/file.js nie pasuje do *.js

globstar ** która pasuje do zera lub więcej segmentów źródła ** musi być ograniczona separatorami / lub początkiem/końcem wzorca glob. Na przykład, **a nie jest prawidłowym wzorcem glob. Również, ** nie może być następowana przez kolejny globstar. Na przykład, **/** nie jest prawidłowym wzorcem glob.

file.js i src/file.js pasują do ** i **/*.js Odwrotnie, README.txt nie pasuje do **/*.js ponieważ źródło kończy się na .txt.

Użyj \* aby wyescapować *

\* pasuje do dosłownego znaku * w źródle.

?, [, ], {, i } muszą być wyescapowane używając \. Te znaki są zarezerwowane do możliwego przyszłego użycia.
Użyj ! jako pierwszego znaku aby zanegować wzorzec glob

file.js pasuje do !*.test.js. src/file.js pasuje do !*.js ponieważ źródło zawiera kilka segmentów.

Typowe konfiguracje

Ta sekcja dostarcza kilka przykładów typowych konfiguracji.

Umieszczanie `import type` i `export type` na początku fragmentów

1
{
2
    "options": {
3
        "groups": [
4
            { "type": true }
5
        ]
6
    }
7
}

Należy zauważyć, że możesz chcieć użyć reguły lint useImportType i jej style aby wymusić użycie import type zamiast import { type }.

Umieszczanie `import type` i `export type` na końcu fragmentów

1
{
2
    "options": {
3
        "groups": [
4
            { "type": false }
5
        ]
6
    }
7
}

Zmiana sortowania identyfikatorów importów na sortowanie leksykograficzne

To dotyczy tylko named importów/eksportów, a nie samego źródła.

1
{
2
  "assist": {
3
    "actions": {
4
      "source": {
5
        "organizeImports": {
6
          "options": {
7
            "identifierOrder": "lexicographic"
8
          }
9
        }
10
      }
11
    }
12
  }
13
}

1
import { var1, var2, var21, var11, var12, var22 } from 'my-package'

code-block.js:1:1 assist/source/organizeImports  FIXABLE  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ℹ The imports and exports are not sorted.
  
  > 1 │ import { var1, var2, var21, var11, var12, var22 } from ‘my-package’
      │ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    2 │ 
  
  ℹ Safe fix: Organize Imports (Biome)
  
    1   │ - import·{·var1,·var2,·var21,·var11,·var12,·var22·}·from·‘my-package’
      1 │ + import·{·var1,·var2,·var11,·var12,·var21,·var22·}·from·‘my-package’
    2 2 │

Zmiana sortowania identyfikatorów importów na sortowanie logiczne

To jest domyślne zachowanie w przypadku, gdy nie nadpiszesz. To dotyczy tylko named importów/eksportów, a nie samego źródła.

1
{
2
  "assist": {
3
    "actions": {
4
      "source": {
5
        "organizeImports": {
6
          "options": {
7
            "identifierOrder": "natural"
8
          }
9
        }
10
      }
11
    }
12
  }
13
}

1
import { var1, var2, var21, var11, var12, var22 } from 'my-package'

code-block.js:1:1 assist/source/organizeImports  FIXABLE  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ℹ The imports and exports are not sorted.
  
  > 1 │ import { var1, var2, var21, var11, var12, var22 } from ‘my-package’
      │ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    2 │ 
  
  ℹ Safe fix: Organize Imports (Biome)
  
    1   │ - import·{·var1,·var2,·var21,·var11,·var12,·var22·}·from·‘my-package’
      1 │ + import·{·var1,·var2,·var11,·var12,·var21,·var22·}·from·‘my-package’
    2 2 │