Maps JavaScript API'yi yükleme

Bu kılavuzda, Maps JavaScript API'nin nasıl yükleneceği gösterilmektedir. Bunu yapmanın üç yolu vardır:

Dinamik Kitaplığı İçe Aktarma özelliğini kullanma

Aşağıdaki snippet'te gösterildiği gibi satır içi önyükleme yükleyicisini uygulama kodunuza ekleyerek Maps JavaScript API'yi yükleyin:

<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>

Önyükleme yükleyici kodunu doğrudan JavaScript kodunuza da ekleyebilirsiniz.

Çalışma zamanında kitaplıkları yüklemek için aşağıdaki kod örneğinde gösterildiği gibi async işlevini kullanarak importLibrary() işlevini çağırmak için await operatörünü kullanın:

TypeScript

let map: google.maps.Map;
async function initMap(): Promise<void> {
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;;
  map = new Map(document.getElementById("map") as HTMLElement, {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

initMap();
index.ts

JavaScript

let map;

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

initMap();
index.js

Gerekli parametreler

  • key: API anahtarınız. Geçerli bir API anahtarı belirtilmediği sürece Maps JavaScript API yüklenmez.

İsteğe bağlı parametreler

  • v: Yüklenecek Maps JavaScript API'nin sürümü.

  • libraries: Yüklenecek diğer Maps JavaScript API kitaplıklarının virgülle ayrılmış listesi. Düzeltilmiş bir kitaplık kümesinin belirtilmesi genellikle önerilmez ancak web sitelerindeki önbelleğe alma davranışını ayrıntılı şekilde ayarlamak isteyen geliştiriciler tarafından kullanılabilir.

  • language: Kullanılacak dil. Bu durum; denetim adlarını, telif hakkı bildirimlerini, arabayla yol tariflerini, denetim etiketlerini ve hizmet isteklerine verilen yanıtları etkilemektedir. Desteklenen dillerin listesini inceleyin.

  • region: Kullanılacak bölge kodu. Bu, belirli bir ülkeye veya bölgeye göre haritanın davranışını değiştirir.

  • solutionChannel: Google Haritalar Platformu, hızla çalışmaya başlamanıza yardımcı olmak için birçok örnek kod türü sağlar. Google, daha karmaşık kod örneklerimizin kullanımını benimsemeyi izlemek ve çözüm kalitesini iyileştirmek için API kodumuza solutionChannel sorgu parametresini örnek kodumuza ekler.

  • authReferrerPolicy: Haritalar JS müşterileri, belirli bir API anahtarını kullanma iznine sahip URL'leri sınırlamak için Cloud Console'da HTTP Yönlendiren Kısıtlamaları yapılandırabilir. Varsayılan olarak, bu kısıtlamalar yalnızca belirli yolların API Anahtarı kullanmasına izin verecek şekilde yapılandırılabilir. Aynı alandaki veya kaynaktaki URL'lerden biri API Anahtarı'nı kullanıyorsa Haritalar JavaScript API'sinden gelen isteklerin yetkilendirilmesi sırasında gönderilen veri miktarını sınırlamak için authReferrerPolicy: "origin" değerini ayarlayabilirsiniz. Bu parametre belirtildiğinde ve Cloud Console'da HTTP Yönlendiren Kısıtlamaları etkinleştirildiğinde, Haritalar JavaScript API'si yalnızca, yolu belirtilen olmadan mevcut web sitesinin alan adıyla eşleşen bir HTTP Yönlendiren Kısıtlaması olduğunda yükleme yapabilir.

NPM js-api-loader paketini kullanın

@googlemaps/js-api-loader paketi NPM paket yöneticisi aracılığıyla yüklenebilir. Aşağıdaki komutu kullanarak yükleyin:

npm install @googlemaps/js-api-loader

Bu paket, aşağıdaki yöntemlerle uygulamaya aktarılabilir:

import { Loader } from "@googlemaps/js-api-loader"

Yükleyici, bir söz ve geri çağırma arayüzü gösterir. Aşağıda, varsayılan Promise yönteminin (load()) kullanımı gösterilmektedir.

TypeScript

const loader = new Loader({
  apiKey: "YOUR_API_KEY",
  version: "weekly",
  ...additionalOptions,
});

loader.load().then(async () => {
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
  map = new Map(document.getElementById("map") as HTMLElement, {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
});
index.ts

JavaScript

const loader = new Loader({
  apiKey: "YOUR_API_KEY",
  version: "weekly",
  ...additionalOptions,
});

loader.load().then(async () => {
  const { Map } = await google.maps.importLibrary("maps");

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

index.js

js-api-loader'ın yer aldığı bir örneği inceleyin.

Eski komut dosyası yükleme etiketini kullan

Eski komut dosyası yükleme etiketi hâlâ destekleniyor. Bu bölüm, eski komut dosyası yükleme etiketinin kullanıldığı entegrasyonları desteklemek için sağlanmıştır. Google, Dinamik Kitaplık Yükleme API'sinin taşınmasını önerir.

Komut dosyası etiketi ekleme

Maps JavaScript API'yi HTML dosyası içine yüklemek için aşağıda gösterildiği gibi bir script etiketi ekleyin.

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

Eski komut dosyası yükleme URL Parametreleri

Bu bölümde, Maps JavaScript API'yi yüklerken komut dosyası yükleme URL'sinin sorgu dizesinde belirtebileceğiniz tüm parametreler açıklanmaktadır. Bazı parametreler zorunluyken diğerleri isteğe bağlıdır. URL'lerde olduğu gibi, tüm parametreler "ve" (&) karakteri kullanılarak ayrılır.

Aşağıdaki örnek URL'de, olası tüm parametreler için yer tutucular vardır:

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

Aşağıdaki script etiketindeki URL, Maps JavaScript API'yi yükler:

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

Gerekli parametreler (eski)

Maps JavaScript API yüklenirken aşağıdaki parametreler gereklidir.

  • key: API anahtarınız. Geçerli bir API anahtarı belirtilmediği sürece Maps JavaScript API yüklenmez.

  • callback: Haritalar JavaScript API'si tamamen yüklendikten sonra çağrılacak bir genel işlevin adı.

İsteğe bağlı parametreler (eski)

Maps JavaScript API'nin belirli bir sürümünü istemek, ek kitaplıklar yüklemek, haritanızı yerelleştirmek veya HTTP yönlendiren kontrolü politikasını belirtmek için bu parametreleri kullanın

  • v: Kullanılacak Maps JavaScript API'nin sürümü.

  • libraries: Yüklenecek diğer Maps JavaScript API kitaplıklarının virgülle ayrılmış listesi.

  • language: Kullanılacak dil. Bu durum; kontrol adlarının, telif hakkı bildirimlerinin, arabayla yol tariflerinin, kontrol etiketlerinin ve hizmet isteklerine verilen yanıtları etkilemektedir. Desteklenen dillerin listesini inceleyin.

  • region: Kullanılacak bölge kodu. Bu, belirli bir ülkeye veya bölgeye göre haritanın davranışını değiştirir.

  • solution_channel: Google Haritalar Platformu, hızla çalışmaya başlamanıza yardımcı olmak için birçok örnek kod türü sağlar. Google, daha karmaşık kod örneklerimizin kullanımını benimsemeyi izlemek ve çözüm kalitesini iyileştirmek için API kodumuza solution_channel sorgu parametresini örnek kodumuza ekler.

  • auth_referrer_policy: Haritalar JS müşterileri, belirli bir API anahtarını kullanma iznine sahip URL'leri sınırlamak için Cloud Console'da HTTP Yönlendiren Kısıtlamaları yapılandırabilir. Varsayılan olarak, bu kısıtlamalar yalnızca belirli yolların API Anahtarı kullanmasına izin verecek şekilde yapılandırılabilir. Aynı alandaki veya kaynaktaki URL'lerden biri API Anahtarı'nı kullanıyorsa Haritalar JavaScript API'sinden gelen isteklerin yetkilendirilmesi sırasında gönderilen veri miktarını sınırlamak için auth_referrer_policy=origin değerini ayarlayabilirsiniz. Bu sürüm 3.46'dan itibaren kullanılabilir. Bu parametre belirtildiğinde ve Cloud Console'da HTTP Yönlendiren Kısıtlamaları etkinleştirildiğinde, Maps JavaScript API yalnızca, yolu belirtilmeden geçerli web sitesinin alanıyla eşleşen bir HTTP Yönlendiren Kısıtlaması varsa yüklenebilir.

Dynamic Library Import API'ye taşı

Bu bölümde, Dynamic Library Import API'yi kullanmak üzere entegrasyonunuzu taşımak için gereken adımlar ele alınmaktadır.

Taşıma adımları

Öncelikle, eski komut dosyası yükleme etiketini satır içi önyükleme yükleyicisi etiketiyle değiştirin.

Önce

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

Sonra

<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>

Ardından, uygulama kodunuzu güncelleyin:

  • initMap() işlevinizi eşzamansız olarak değiştirin.
  • İhtiyacınız olan kitaplıkları yüklemek ve bunlara erişmek için importLibrary() numaralı telefonu arayın.

Önce

let map;

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

window.initMap = initMap;

Sonra

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