Wczytywanie interfejsu Maps JavaScript API

Z tego przewodnika dowiesz się, jak wczytać interfejs Maps JavaScript API. Możesz to zrobić na 3 sposoby:

• użyć dynamicznego importu biblioteki
• użyć tagu bezpośredniego wczytywania skryptu
• użyć pakietu NPM js-api-loader.

Używanie dynamicznego importu biblioteki

Dynamiczny import biblioteki umożliwia wczytywanie bibliotek w czasie działania. Dzięki temu możesz poprosić o potrzebne biblioteki w momencie, gdy ich potrzebujesz, a nie wszystkie naraz podczas wczytywania. Chroni to też stronę przed wielokrotnym wczytywaniem interfejsu Maps JavaScript API.

Aby wczytać interfejs Maps JavaScript API, dodaj do kodu aplikacji wbudowany program wczytujący, jak pokazano w tym fragmencie kodu:

<script>
  (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
    key: "YOUR_API_KEY",
    v: "weekly",
    // Use the 'v' parameter to indicate the version to use (weekly, beta, alpha, etc.).
    // Add other bootstrap parameters as needed, using camel case.
  });
</script>

Kod programu wczytującego możesz też dodać bezpośrednio do kodu JavaScript.

Aby wczytać biblioteki w czasie działania, użyj operatora await, aby wywołać funkcję importLibrary() w funkcji async. Zadeklarowanie zmiennych dla potrzebnych klas pozwala pominąć używanie kwalifikowanej ścieżki (np. google.maps.Map), jak pokazano w tym przykładzie kodu:

async function init() {
    // Import the needed libraries.
    await google.maps.importLibrary('maps');

    // Access the map.
    const mapElement = document.querySelector('gmp-map');
    // Access the underlying map object.
    const innerMap = mapElement.innerMap;

    console.log({ mapElement, innerMap });
}

void init();
index.js

Funkcja może też wczytywać biblioteki bez deklarowania zmiennej dla potrzebnych klas. Jest to szczególnie przydatne, jeśli mapa została dodana za pomocą elementu gmp-map. Bez zmiennej musisz używać kwalifikowanych ścieżek, np. google.maps.Map:

let map;
let center =  { lat: -34.397, lng: 150.644 };

async function initMap() {
  await google.maps.importLibrary("maps");
  await google.maps.importLibrary("marker");

  map = new google.maps.Map(document.getElementById("map"), {
    center,
    zoom: 8,
    mapId: "DEMO_MAP_ID",
  });

  addMarker();
}

async function addMarker() {
  const marker = new google.maps.marker.AdvancedMarkerElement({
    map,
    position: center,
  });
}

initMap();

Możesz też wczytać biblioteki bezpośrednio w kodzie HTML, jak pokazano tutaj:

<script>
google.maps.importLibrary("maps");
google.maps.importLibrary("marker");
</script>

Dowiedz się, jak przeprowadzić migrację do interfejsu Dynamic Library Loading API.

Wymagane parametry

• key: Twój klucz interfejsu API. Interfejs Maps JavaScript API nie wczyta się, jeśli nie zostanie podany prawidłowy klucz interfejsu API.

Parametry opcjonalne

• v: wersja interfejsu Maps JavaScript API, która ma zostać wczytana.

• libraries: tablica dodatkowych bibliotek interfejsu Maps JavaScript API , które mają zostać wstępnie wczytane. Określanie stałego zestawu bibliotek nie jest na ogół zalecane, ale jest dostępne dla deweloperów, którzy chcą precyzyjnie dostosować działanie pamięci podręcznej w swojej witrynie. Przed użyciem każdej wybranej biblioteki nadal trzeba wywołać funkcję google.maps.importLibrary().

• language: język, którego chcesz używać. Wpływa to na nazwy elementów sterujących, informacje o prawach autorskich, wskazówki dojazdu i etykiety elementów sterujących oraz odpowiedzi na żądania usług. Zobacz listę obsługiwanych języków.

• region: kod regionu , którego chcesz używać. Zmienia to działanie interfejsu API w zależności od danego kraju lub terytorium.

• authReferrerPolicy: klienci korzystający z Maps JS mogą skonfigurować ograniczenia dotyczące odsyłacza HTTP w konsoli Cloud, aby ograniczyć adresy URL, które mogą używać określonego klucza interfejsu API. Domyślnie te ograniczenia można skonfigurować tak, aby tylko określone ścieżki mogły używać klucza interfejsu API. Jeśli dowolny adres URL w tej samej domenie lub źródle może używać klucza interfejsu API, możesz ustawić authReferrerPolicy: "origin", aby ograniczyć ilość danych wysyłanych podczas autoryzowania żądań z interfejsu Maps JavaScript API. Gdy ten parametr jest określony, a w konsoli Cloud włączone są ograniczenia dotyczące odsyłacza HTTP, interfejs Maps JavaScript API będzie można wczytać tylko wtedy, gdy istnieje ograniczenie dotyczące odsyłacza HTTP, które pasuje do domeny bieżącej witryny bez określonej ścieżki.

• mapIds: tablica identyfikatorów map. Powoduje wstępne wczytanie konfiguracji dla określonych identyfikatorów map. Określanie identyfikatorów map w tym miejscu nie jest wymagane do korzystania z identyfikatorów map, ale jest dostępne dla deweloperów, którzy chcą precyzyjnie dostosować wydajność sieci.

• channel: zobacz Śledzenie wykorzystania według kanału.

Używanie tagu bezpośredniego wczytywania skryptu

Z tej sekcji dowiesz się, jak używać tagu bezpośredniego wczytywania skryptu. Ponieważ skrypt bezpośredni wczytuje biblioteki podczas wczytywania mapy, może uprościć mapy utworzone za pomocą elementu gmp-map, eliminując konieczność jawnego żądania bibliotek w czasie działania. Ponieważ tag bezpośredniego wczytywania skryptu wczytuje wszystkie żądane biblioteki naraz podczas wczytywania skryptu, w przypadku niektórych aplikacji może to mieć wpływ na wydajność. Tag bezpośredniego wczytywania skryptu należy umieścić tylko raz na stronie.

Uwaga: Funkcję importLibrary możesz wywołać po zakończeniu wczytywania tagu bezpośredniego wczytywania skryptu.

Dodawanie tagu skryptu

Aby wczytać interfejs Maps JavaScript API w pliku HTML, dodaj tag script, jak pokazano poniżej.

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&callback=initMap">
</script>

Parametry adresu URL bezpośredniego wczytywania skryptu

W tej sekcji omawiamy wszystkie parametry, które możesz określić w ciągu zapytania adresu URL wczytywania skryptu podczas wczytywania interfejsu Maps JavaScript API. Niektóre parametry są wymagane, a inne opcjonalne. Jak to jest standardem w adresach URL, wszystkie parametry są rozdzielone znakiem ampersand (&).

Ten przykładowy adres URL zawiera obiekty zastępcze dla wszystkich możliwych parametrów:

https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY
&loading=async
&callback=FUNCTION_NAME
&v=VERSION
&libraries="LIBRARIES"
&language="LANGUAGE"
&region="REGION"
&auth_referrer_policy="AUTH_REFERRER_POLICY"
&map_ids="MAP_IDS"
&channel="CHANNEL"
&solution_channel="SOLUTION_IDENTIFIER"

Adres URL w tym przykładowym tagu script wczytuje interfejs Maps JavaScript API:

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&callback=initMap">
</script>

Wymagane parametry (bezpośrednie) {:.hide-from-toc}

Podczas wczytywania interfejsu Maps JavaScript API wymagane są te parametry:

• key: Twój klucz interfejsu API. Interfejs Maps JavaScript API nie wczyta się, jeśli nie zostanie podany prawidłowy klucz interfejsu API.

Parametry opcjonalne (bezpośrednie) {:.hide-from-toc}

Użyj tych parametrów, aby poprosić o konkretną wersję interfejsu Maps JavaScript API, wczytać dodatkowe biblioteki, zlokalizować mapę lub określić zasadę sprawdzania odsyłacza HTTP.

• loading: strategia wczytywania kodu, której może używać interfejs Maps JavaScript API. Ustaw wartość async, aby wskazać, że interfejs Maps JavaScript API nie został wczytany synchronicznie i że żadna część kodu JavaScript nie jest wywoływana przez zdarzenie load skryptu. Aby zwiększyć wydajność, zalecamy ustawienie tej wartości na async zawsze, gdy jest to możliwe. (Aby wykonywać działania, gdy interfejs Maps JavaScript API jest dostępny, użyj parametru callback.) Dostępne od wersji 3.55.

• callback: nazwa funkcji globalnej, która ma zostać wywołana po całkowitym wczytaniu interfejsu Maps JavaScript API.

• v: wersja interfejsu Maps JavaScript API, której chcesz używać.

• libraries: lista dodatkowych bibliotek interfejsu Maps JavaScript API, rozdzielona przecinkami, które mają zostać wczytane.

• language: język, którego chcesz używać. Wpływa to na nazwy elementów sterujących, informacje o prawach autorskich, wskazówki dojazdu i etykiety elementów sterujących oraz odpowiedzi na żądania usług. Zobacz listę obsługiwanych języków.

• region: kod regionu , którego chcesz używać. Zmienia to działanie interfejsu API w zależności od danego kraju lub terytorium.

• auth_referrer_policy: klienci mogą skonfigurować ograniczenia dotyczące odsyłacza HTTP w konsoli Cloud, aby ograniczyć adresy URL, które mogą używać określonego klucza interfejsu API. Domyślnie te ograniczenia można skonfigurować tak, aby tylko określone ścieżki mogły używać klucza interfejsu API. Jeśli dowolny adres URL w tej samej domenie lub źródle może używać klucza interfejsu API, możesz ustawić auth_referrer_policy=origin, aby ograniczyć ilość danych wysyłanych podczas autoryzowania żądań z interfejsu Maps JavaScript API. Ta opcja jest dostępna od wersji 3.46. Gdy ten parametr jest określony, a w konsoli Cloud włączone są ograniczenia dotyczące odsyłacza HTTP, interfejs Maps JavaScript API będzie można wczytać tylko wtedy, gdy istnieje ograniczenie dotyczące odsyłacza HTTP , które pasuje do domeny bieżącej witryny bez określonej ścieżki.

• map_ids: lista identyfikatorów map rozdzielona przecinkami. Powoduje wstępne wczytanie konfiguracji dla określonych identyfikatorów map. Określanie identyfikatorów map w tym miejscu nie jest wymagane do korzystania z identyfikatorów map, ale jest dostępne dla deweloperów, którzy chcą precyzyjnie dostosować wydajność sieci.

• channel: zobacz Śledzenie wykorzystania według kanału.

Używanie pakietu NPM js-api-loader

Wskazówka: Wersja v2.0.0 to poważna refaktoryzacja, która zastępuje starą klasę Loader interfejsem API składającym się z 2 funkcji: setOptions() i importLibrary(). Ta zmiana umożliwia dynamiczne wczytywanie poszczególnych bibliotek interfejsu API Map Google na żądanie, co pozwala opóźnić pobieranie funkcji i poprawić początkową wydajność strony.

Dostępny jest pak0iet @googlemaps/js-api-loader, który można wczytać za pomocą menedżera pakietów NPM. Zainstaluj go za pomocą tego polecenia:

npm install @googlemaps/js-api-loader

Zaimportuj pakiet, jak pokazano tutaj:

TypeScript

// Import the needed libraries.
import { setOptions, importLibrary } from '@googlemaps/js-api-loader';
index.ts

Uwaga: przeczytaj przewodnik dotyczący korzystania z TypeScript i Map Google.

JavaScript

// Import the needed libraries.
import { setOptions, importLibrary } from '@googlemaps/js-api-loader';
index.js

Moduł wczytujący używa obiektów typu Promise, aby udostępniać biblioteki. Wczytaj biblioteki za pomocą metody importLibrary(). Ten przykład pokazuje, jak użyć programu wczytującego do wczytania mapy:

TypeScript

// Import the needed libraries.
import { setOptions, importLibrary } from '@googlemaps/js-api-loader';

const API_KEY = 'AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8';

async function init(): Promise<void> {
    // Set loader options.
    setOptions({
        key: API_KEY,
    });

    // Load the Maps library.
    const { Map } = await importLibrary('maps');

    // Set map options.
    const mapOptions = {
        center: { lat: 48.8566, lng: 2.3522 },
        zoom: 3,
    };

    // Declare the map.
    new Map(document.getElementById('map')!, mapOptions);
}

void init();
index.ts

Uwaga: przeczytaj przewodnik dotyczący korzystania z TypeScript i Map Google.

JavaScript

// Import the needed libraries.
import { setOptions, importLibrary } from '@googlemaps/js-api-loader';

const API_KEY = 'AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8';

async function init() {
    // Set loader options.
    setOptions({
        key: API_KEY,
    });

    // Load the Maps library.
    const { Map } = await importLibrary('maps');

    // Set map options.
    const mapOptions = {
        center: { lat: 48.8566, lng: 2.3522 },
        zoom: 3,
    };

    // Declare the map.
    new Map(document.getElementById('map'), mapOptions);
}

void init();
index.js

Zobacz pełny przykładowy kod.

Migracja do interfejsu Dynamic Library Import API

Z tej sekcji dowiesz się, jak przeprowadzić migrację integracji, aby korzystać z interfejsu Dynamic Library Import API.

Kroki migracji

Najpierw zastąp tag bezpośredniego wczytywania skryptu tagiem wbudowanego narzędzia do wczytywania.

Przed

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&libraries=maps&callback=initMap">
</script>

Po

<script>
  (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
    key: "YOUR_API_KEY",
    v: "weekly",
    // Use the 'v' parameter to indicate the version to use (weekly, beta, alpha, etc.).
    // Add other bootstrap parameters as needed, using camel case.
  });
</script>

Następnie zaktualizuj kod aplikacji:

• Zmień funkcję initMap() na asynchroniczną.
• Wywołaj funkcję importLibrary(), aby wczytać i uzyskać dostęp do potrzebnych bibliotek.

Przed

let map;

function initMap() {
  map = new google.maps.Map(document.getElementById("map"), {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

window.initMap = initMap;

Po

let map;
// initMap is now async
async function initMap() {
    // Request libraries when needed, not in the script tag.
    const { Map } = await google.maps.importLibrary("maps");
    // Short namespaces can be used.
    map = new Map(document.getElementById("map"), {
        center: { lat: -34.397, lng: 150.644 },
        zoom: 8,
    });
}

initMap();