HTML Academy · Lekcja

Mapy importu — importmap

Mapowanie skróconych specyfikatorów modułów na adresy URL za pomocą importmap

Mapy importu — importmap to bezpłatna lekcja HTML Academy na CoddyKit. To lekcja 2 z 4. Możesz przeczytać całą lekcję poniżej za darmo — a potem ćwiczyć ją interaktywnie w przeglądarce z wbudowanym edytorem kodu i tutorem AI dostępnym 24/7. To część ścieżki edukacyjnej HTML Academy, a Twój postęp synchronizuje się między webem a aplikacją CoddyKit. Kurs HTML Academy zawiera 4 lekcji w sumie.

Problem nazw bezpośrednich

W Node import "lodash" działa, ponieważ resolver znajduje node_modules/lodash. Przeglądarki nie mają katalogu node_modules — potrzebują rzeczywistego adresu URL. Bez dodatkowej konfiguracji import "lodash" zgłasza błąd „Failed to resolve module specifier”.

Działanie map importów

Mapa importów deklaruje słownik JSON, który mapuje nazwy bezpośrednie (oraz prefiksy adresów URL) na rzeczywiste adresy URL. Podczas rozwiązywania modułu przeglądarka sprawdza mapę i zamienia import "lodash" na pobranie z skonfigurowanego adresu URL.

<script type="importmap">
{
  "imports": {
    "lodash": "https://esm.sh/lodash@4.17.21",
    "preact": "https://esm.sh/preact"
  }
}
</script>

Kolejność deklaracji ma znaczenie

Mapa importów musi znajdować się przed każdym elementem <script type="module">, który używa nazw bezpośrednich — gdy moduł zacznie już rozwiązywać importy, mapa zostaje zablokowana. Element <script type="importmap"> należy umieścić w pobliżu początku sekcji <head>.

Mapowania prefiksów

Wpisy kończące się ukośnikiem dopasowują prefiksy adresów URL: "@/": "/src/" mapuje każdy import "@/utils/sum.js" na /src/utils/sum.js. W ten sposób można symulować składnię „aliasów”, powszechnie obsługiwaną przez bundlery.

Wersjonowanie za pomocą mapy

Mapa importów centralizuje wybór wersji: zmiana "react" z esm.sh/react@18 na esm.sh/react@19 w jednym miejscu sprawia, że każdy importujący moduł korzysta z nowego adresu URL. Bez mapy importów każde miejsce importu ma własną, zakodowaną na stałe wersję.

Zakresy

Klucz scopes umożliwia definiowanie różnych mapowań dla różnych części witryny. W obrębie /admin/ może być potrzebna nowsza wersja zależności niż w /public/; zakresy pozwalają kierować mapowania na podstawie ścieżki.

{
  "imports": { "lodash": "https://esm.sh/lodash@4" },
  "scopes": {
    "/admin/": { "lodash": "https://esm.sh/lodash@5" }
  }
}

Jedna mapa na dokument

Każdy dokument może zawierać najwyżej jeden element <script type="importmap">. Umieszczenie dwóch takich elementów na tej samej stronie jest nieprawidłowe; aby połączyć wpisy, należy scalić ich zawartość w jednym bloku.

Zewnętrzne mapy importów

Mapę można umieścić pod zewnętrznym adresem URL za pomocą <script type="importmap" src="map.json">. Obsługa przeglądarek jest nowsza niż w przypadku map osadzonych, ale obecnie szeroko dostępna; rozwiązanie to jest przydatne, gdy duża mapa ma być buforowana niezależnie od dokumentu.

Generowanie map importów

Narzędzia takie jak JSPM Generator i tryb --servedir programu esbuild automatycznie generują mapy importów na podstawie package.json. Wygenerowane mapy zawierają wszystkie zależności przechodnie i mapują je na adresy URL CDN-u, umożliwiając pracę bez node_modules.

Obsługa przeglądarek

Mapy importów są obsługiwane przez Chrome, Edge, Safari i Firefox. Starsze przeglądarki ignorują element <script type="importmap">, przez co nazwy bezpośrednie nie działają. Aby zapewnić szeroką obsługę starszych przeglądarek, należy zbudować aplikację za pomocą bundlera, który rozwiąże specyfikatory podczas kompilacji, a następnie serwować zwykłe adresy URL.

Opcja polyfillu

Polyfill ES Module Shims (es-module-shims.js) dodaje obsługę map importów — oraz kilku nowszych funkcji — w starszych przeglądarkach. Należy dołączyć go przed skryptem importmap. Większość nowoczesnych projektów pomija polyfill i korzysta z natywnej obsługi.

Sprawdzenie wiedzy

Dlaczego element <script type="importmap"> musi znajdować się przed każdym skryptem modułu używającym nazw bezpośrednich?

Podsumowanie

Mapy importów mapują nazwy bezpośrednie i prefiksy adresów URL na rzeczywiste adresy URL, przywracając w przeglądarce znany z Node zapis „import lodash”. Należy deklarować je raz na dokument, przed każdym skryptem modułu; opcjonalnie można umieścić je zewnętrznie za pomocą src, a zakresy umożliwiają nadpisywanie mapowań dla poszczególnych ścieżek. W połączeniu z CDN-em (esm.sh, jsdelivr) pozwalają pracować bez node_modules.

Często zadawane pytania

Czy lekcja „Mapy importu — importmap” jest bezpłatna?

Tak — pełny tekst „Mapy importu — importmap” jest dostępny za darmo tutaj w sieci. Aby ćwiczyć ją interaktywnie (wbudowany edytor kodu i tutor AI dostępny 24/7) i odblokować resztę kursu HTML Academy, przejdź na CoddyKit PRO. Kurs HTML Academy zawiera 4 lekcji w sumie.

Co nauczysz się w „Mapy importu — importmap”?

Mapowanie skróconych specyfikatorów modułów na adresy URL za pomocą importmap Ćwiczysz HTML Academy z praktycznym kodem, który uruchamiasz bezpośrednio w przeglądarce, a tutor AI dostępny 24/7 odpowiada na Twoje pytania podczas pracy nad lekcją.

Czy potrzebuję doświadczenia, aby zacząć HTML Academy?

Nie wymagamy żadnego doświadczenia. HTML Academy w CoddyKit jest strukturyzowany dla początkujących i zaawansowanych użytkowników, więc możesz zacząć tutaj lub od początku i uczyć się w swoim tempie. To lekcja 2 z 4.

Ile czasu zajmuje lekcja „Mapy importu — importmap”?

Większość lekcji CoddyKit trwa około 5–10 minut. Każda lekcja to mały, interaktywny krok, dzięki czemu robisz systematyczne postępy i zawsze wracasz dokładnie do tego samego miejsca — na webie i w aplikacji.

Czy mogę pisać i uruchamiać kod w tej lekcji HTML Academy?

Tak. Każda lekcja HTML Academy zawiera wbudowany edytor kodu, więc piszesz i uruchamiasz prawdziwy kod bezpośrednio w przeglądarce i od razu otrzymujesz sprzężenie zwrotne od AI — bez konfiguracji na komputerze.

Wszystkie lekcje w tym kursie

← Powrót do HTML Academy