Wczytywanie interfejsu Maps JavaScript API

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

• Użyj dynamicznego importowania bibliotek.
• Używanie tagu bezpośredniego wczytywania skryptu
• Użyj pakietu NPM js-api-loader.

Używanie dynamicznego importu bibliotek

Importowanie bibliotek dynamicznych umożliwia wczytywanie bibliotek w czasie działania programu. Dzięki temu możesz poprosić o potrzebne biblioteki w momencie, gdy ich potrzebujesz, zamiast pobierać je wszystkie naraz podczas wczytywania. Zapobiega też wielokrotnemu wczytywaniu interfejsu Maps JavaScript API na stronie.

Wczytaj interfejs Maps JavaScript API, dodając do kodu aplikacji wbudowany program do wczytywania, jak pokazano w tym fragmencie:

<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 narzędzia do wczytywania możesz też dodać bezpośrednio do kodu JavaScript.

Aby wczytać biblioteki w czasie działania programu, użyj operatora await do wywołania funkcji importLibrary() w funkcji async. Deklarowanie 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, co jest 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 HTML-u, jak pokazano poniżej:

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

Dowiedz się, jak przejść na interfejs Dynamic Library Loading API.

Wymagane parametry

• key: Twój klucz interfejsu API. Interfejs Maps JavaScript API nie zostanie wczytany, jeśli nie podasz prawidłowego klucza API.

Parametry opcjonalne

• v: wersja interfejsu Maps JavaScript API do wczytania. Jeśli nie określisz wyraźnie kanału ani wersji, domyślnie otrzymasz kanał tygodniowy. Jeśli po przejściu z subskrypcji Premium nie określisz kanału ani wersji, domyślnie otrzymasz kanał kwartalny. Jeśli podasz nieprawidłową wersję, otrzymasz domyślny kanał. Więcej informacji

• libraries: tablica dodatkowych bibliotek Maps JavaScript API, które mają być wstępnie wczytane. Określanie stałego zestawu bibliotek nie jest zwykle 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 należy wywołać funkcję google.maps.importLibrary().

• language: Język, którego chcesz użyć. Dotyczy to nazw elementów sterujących, informacji o prawach autorskich, wskazówek dojazdu i etykiet elementów sterujących oraz odpowiedzi na żądania usług. Zobacz listę obsługiwanych języków.

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

• authReferrerPolicy: klienci korzystający z interfejsu Maps JS mogą skonfigurować w konsoli Cloud ograniczenia dotyczące odsyłającego HTTP, aby określić, które adresy URL mogą używać danego klucza interfejsu API. Domyślnie te ograniczenia można skonfigurować tak, aby tylko określone ścieżki mogły używać klucza API. Jeśli dowolny adres URL w tej samej domenie lub pochodzący z tego samego źródła może używać klucza interfejsu API, możesz ustawić parametr authReferrerPolicy: "origin", aby ograniczyć ilość danych wysyłanych podczas autoryzowania żądań z interfejsu Maps JavaScript API. Jeśli ten parametr jest określony, a w Konsoli Cloud włączone są ograniczenia dotyczące odsyłacza HTTP, interfejs Maps JavaScript API będzie mógł się 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 tutaj identyfikatorów map nie jest wymagane do ich używania, ale jest dostępne dla deweloperów, którzy chcą precyzyjnie dostosować wydajność sieci.

• channel: zobacz Śledzenie wykorzystania na poszczególnych kanałach.

Używanie tagu bezpośredniego wczytywania skryptu

W tej sekcji dowiesz się, jak używać tagu bezpośredniego wczytywania skryptu. Skrypt bezpośredni wczytuje biblioteki podczas wczytywania mapy, co może uprościć mapy utworzone za pomocą elementu gmp-map, ponieważ nie trzeba jawnie żądać bibliotek w czasie działania programu. Tag bezpośredniego ładowania skryptu ładuje wszystkie żądane biblioteki jednocześnie po załadowaniu skryptu, więc w przypadku niektórych aplikacji może to mieć wpływ na wydajność. Tag bezpośredniego ładowania skryptu należy umieszczać tylko raz na wczytanie strony.

Dodawanie tagu skryptu

Aby wczytać interfejs Maps JavaScript API w pliku HTML, dodaj tag script w sposób pokazany 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. Zgodnie ze standardem adresów URL wszystkie parametry są rozdzielone znakiem ampersand (&).

Ten przykładowy adres URL zawiera obiekty zastępcze 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"

URL w tagu script w poniższym przykładzie wczytuje interfejs Maps JavaScript API:

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

Parametry wymagane (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 zostanie wczytany, 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 określoną wersję interfejsu Maps JavaScript API, wczytać dodatkowe biblioteki, zlokalizować mapę lub określić zasady sprawdzania strony odsyłającej HTTP.

• loading: strategia wczytywania kodu, której może używać Maps JavaScript API. Ustaw wartość async, aby wskazać, że interfejs Maps JavaScript API nie został wczytany synchronicznie i że żadne zdarzenie load skryptu nie wywołuje kodu JavaScript. W celu zwiększenia wydajności zalecamy ustawienie tej opcji na async, jeśli 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 załadowaniu interfejsu Maps JavaScript API.

• v: wersja interfejsu Maps JavaScript API, która ma być używana.

• libraries: lista rozdzielona przecinkami dodatkowych bibliotek Maps JavaScript API do wczytania.

• language: Język, którego chcesz użyć. Dotyczy to nazw elementów sterujących, informacji o prawach autorskich, wskazówek dojazdu i etykiet elementów sterujących, a także odpowiedzi na żądania usług. Zobacz listę obsługiwanych języków.

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

• auth_referrer_policy: Klienci mogą skonfigurować w konsoli Cloud ograniczenia dotyczące strony odsyłającej HTTP, aby określić, które adresy URL mogą używać danego klucza 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 pochodzeniu może używać klucza interfejsu API, możesz ustawić parametr auth_referrer_policy=origin, aby ograniczyć ilość danych wysyłanych podczas autoryzowania żądań z interfejsu JavaScript API Map Google. Ta funkcja 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 rozdzielonych przecinkami. Powoduje wstępne wczytanie konfiguracji dla określonych identyfikatorów map. Określanie tutaj identyfikatorów map nie jest wymagane do ich używania, ale jest dostępne dla deweloperów, którzy chcą precyzyjnie dostosować wydajność sieci.

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

Korzystanie z pakietu NPM js-api-loader

Dostępny jest pakiet @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 w sposób pokazany tutaj:

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

// 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. Wczytuj biblioteki za pomocą metody importLibrary(). Poniższy przykład pokazuje, jak użyć modułu wczytującego do wczytania mapy:

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

const API_KEY = 'GOOGLE_MAPS_API_KEY';

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

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

const API_KEY = 'GOOGLE_MAPS_API_KEY';

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 API importu bibliotek dynamicznych

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

Etapy migracji

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

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ć biblioteki, których potrzebujesz, i uzyskać do nich dostęp.

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();