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 importu biblioteki
• użyj tagu bezpośredniego wczytywania skryptu
• użyj pakietu js-api-loader NPM.

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życie kwalifikowanej ścieżki (np. google.maps.Map), jak pokazano w tym przykładzie kodu:

async function initMap() {
    // Import the needed libraries.
    await google.maps.importLibrary('maps');
    // Create the map.
    const mapElement = document.querySelector('gmp-map');
    // Access the underlying map object.
    const innerMap = mapElement.innerMap;
}
initMap();
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();

Biblioteki możesz też wczytać 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 zostanie wczytany, 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 pochodzący z tego samego źródła 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. Tag bezpośredniego wczytywania skryptu wczytuje wszystkie żądane biblioteki naraz podczas wczytywania skryptu, co może mieć wpływ na wydajność niektórych aplikacji. Tag bezpośredniego wczytywania skryptu należy umieścić tylko raz na stronie.

Dodawanie tagu skryptu

Aby wczytać interfejs Maps JavaScript API wbudowany w plik 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

Z tej sekcji dowiesz się o wszystkich parametrach, 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 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ć 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 żaden kod JavaScript nie jest wywoływany 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 pochodzący z tego samego źródła 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. Jest to dostępne 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.

• internal_usage_attribution_ids: lista identyfikatorów atrybucji wykorzystania rozdzielona przecinkami, które pomagają Google zrozumieć, które biblioteki i przykłady są przydatne dla deweloperów, np. wykorzystanie biblioteki klastrowania znaczników. Aby zrezygnować z wysyłania identyfikatora atrybucji wykorzystania, możesz bezpiecznie usunąć tę właściwość lub zastąpić jej wartość pustym ciągiem. Wysyłane będą tylko unikalne wartości. Więcej informacji znajdziesz w artykule Parametr rozwiązań Google Maps Platform.

Używanie pakietu js-api-loader NPM

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:

// 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(). Ten przykład pokazuje, jak używać programu wczytującego do wczytywania mapy:

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

const API_KEY = 'AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8';

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

    // 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.
    const map = new Map(
        document.getElementById('map') as HTMLElement,
        mapOptions
    );
}

initMap();
index.ts

// Import the needed libraries.
import { setOptions, importLibrary } from '@googlemaps/js-api-loader';
const API_KEY = 'AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8';
async function initMap() {
    // Set loader options.
    setOptions({
        key: API_KEY,
        v: 'weekly',
    });
    // 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.
    const map = new Map(document.getElementById('map'), mapOptions);
}
initMap();
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();