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ık içe aktarma özelliğini kullanın.
• Doğrudan komut dosyası yükleme etiketini kullanma
• NPM js-api-loader paketini kullanma

Dinamik kitaplık içe aktarmayı kullanma

Dinamik kitaplık içe aktarma, kitaplıkları çalışma zamanında yükleme olanağı sağlar. Bu sayede, yükleme sırasında hepsini birden istemek yerine ihtiyaç duyduğunuz anda gerekli kitaplıkları isteyebilirsiniz. Ayrıca sayfanızın Maps JavaScript API'yi birden çok kez yüklemesini de engeller.

Aşağıdaki snippet'te gösterildiği gibi, satır içi önyükleyiciyi 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>

Bootstrap yükleyici kodunu doğrudan JavaScript kodunuza da ekleyebilirsiniz.

Kitaplıkları çalışma zamanında yüklemek için async işlevinden importLibrary() işlevini çağırmak üzere await operatörünü kullanın. Gerekli sınıflar için değişkenleri tanımlamak, aşağıdaki kod örneğinde gösterildiği gibi nitelikli bir yol (ör. google.maps.Map) kullanmayı atlamanıza olanak tanır:

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

Uygulamanızın aynı anda birden fazla kitaplığa ihtiyacı olduğunda bunları paralel olarak istemek için Promise.all() kullanın:

const [{ Place }, { AdvancedMarkerElement }] = await Promise.all([
  google.maps.importLibrary('places'),
  google.maps.importLibrary('marker'),
]);

await google.maps.importLibrary() yöntemini ayrı satırlarda sırayla çağırmaktan kaçının. Sıralı await ifadeleri, her kitaplık bir sonrakini istemeden önce indirme ve başlatma işlemini tamamlayana kadar yürütmeyi engeller. Bu da yükleme süresini artıran bir ağ şelalesi oluşturur. Promise.all(), tüm kitaplık indirmelerini aynı anda başlatır ve hepsi hazır olduğunda tamamlar.

İşleviniz, gerekli sınıflar için değişken tanımlamadan da kitaplıkları yükleyebilir. Bu, özellikle gmp-map öğesini kullanarak harita eklediyseniz faydalıdır. Değişken olmadan, nitelikli yollar kullanmanız gerekir. Örneğin, google.maps.Map:

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

async function initMap() {
  await Promise.all([
    google.maps.importLibrary("maps"),
    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();

Alternatif olarak, kitaplıkları burada gösterildiği gibi doğrudan HTML'ye yükleyebilirsiniz:

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

Dinamik Kitaplık Yükleme API'sine nasıl geçiş yapacağınızı öğrenin.

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 sürümü. Bir kanalı veya sürümü açıkça belirtmezseniz varsayılan olarak haftalık kanalı alırsınız. Premium plandan geçiş yaptıysanız ve açıkça bir kanal veya sürüm belirtmediyseniz varsayılan olarak üç aylık kanalı alırsınız. Geçersiz bir sürüm belirtirseniz varsayılan kanalınızı alırsınız. Daha fazla bilgi edinin.

• libraries: Önceden yüklemeye başlamak için ek Maps JavaScript API kitaplıklarından oluşan bir dizi. Sabit bir kitaplık grubu belirtmek genellikle önerilmez ancak web sitelerindeki önbelleğe alma davranışını hassas bir şekilde ayarlamak isteyen geliştiriciler için kullanılabilir. Seçilen her kitaplık için kullanımdan önce google.maps.importLibrary() işlevini çağırmak yine de önemlidir.

• language: Kullanılacak dil. Bu durum; kontrollerin adlarını, telif hakkı bildirimlerini, sürüş talimatlarını, kontrol etiketlerini ve hizmet isteklerine verilen yanıtları etkiler. Desteklenen dillerin listesini inceleyin.

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

• authReferrerPolicy: Maps JS müşterileri, belirli bir API anahtarını kullanmasına izin verilen URL'leri sınırlamak için Cloud Console'da HTTP yönlendiren kısıtlamalarını 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ı alan veya kaynakta bulunan herhangi bir URL API anahtarını kullanabilirse Maps JavaScript API'den gelen istekleri yetkilendirirken 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, Maps JavaScript API yalnızca mevcut web sitesinin alanıyla eşleşen ve yol belirtilmeyen bir HTTP Yönlendiren Kısıtlaması varsa yüklenebilir.

• mapIds: Harita kimlikleri dizisi. Belirtilen harita kimliklerinin yapılandırmasının önceden yüklenmesine neden olur. Harita kimliklerinin kullanımı için harita kimliklerinin burada belirtilmesi zorunlu değildir ancak ağ performansını hassas bir şekilde ayarlamak isteyen geliştiriciler bu özelliği kullanabilir.

• channel: Kanal başına kullanım takibi bölümüne bakın.

Doğrudan komut dosyası yükleme etiketini kullanma

Bu bölümde, doğrudan komut dosyası yükleme etiketinin nasıl kullanılacağı gösterilmektedir. Doğrudan komut dosyası, harita yüklendiğinde kitaplıkları yüklediği için çalışma zamanında kitaplıkları açıkça isteme ihtiyacını ortadan kaldırarak gmp-map öğesi kullanılarak oluşturulan haritaları basitleştirebilir. Doğrudan komut dosyası yükleme etiketi, komut dosyası yüklendiğinde istenen tüm kitaplıkları tek seferde yüklediğinden bazı uygulamalarda performans etkilenebilir. Doğrudan komut dosyası yükleme etiketini sayfa yükleme başına yalnızca bir kez ekleyin.

Komut dosyası etiketi ekleme

Maps JavaScript API'yi bir HTML dosyasına satır içi olarak yüklemek için aşağıdaki gibi bir script etiketi ekleyin.

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

Doğrudan 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 ele alınmaktadır. Bazı parametreler zorunlu, bazıları ise isteğe bağlıdır. URL'lerde standart olduğu gibi, tüm parametreler "ve" işareti (&) kullanılarak ayrılır.

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

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"

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

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

Gerekli parametreler (doğrudan) {:.hide-from-toc}

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.

İsteğe bağlı parametreler (doğrudan) {:.hide-from-toc}

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.

• loading: Maps JavaScript API'nin kullanabileceği kod yükleme stratejisi. Maps JavaScript API'nin eşzamanlı olarak yüklenmediğini ve komut dosyasının load etkinliği tarafından herhangi bir JavaScript kodunun tetiklenmediğini belirtmek için async olarak ayarlayın. Daha iyi performans için mümkün olduğunda bu ayarı async olarak belirlemeniz önemle tavsiye edilir. (Maps JavaScript API kullanılabilir olduğunda işlem yapmak için callback parametresini kullanın.) 3.55 sürümünden itibaren kullanılabilir.

• callback: Maps JavaScript API tamamen yüklendikten sonra çağrılacak global işlevin adı.

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

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

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

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

• auth_referrer_policy: Müşteriler, belirli bir API anahtarının kullanılmasına izin verilen URL'leri sınırlamak için Cloud Console'da HTTP yönlendiren kısıtlamalarını 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ı alan veya kaynakta bulunan herhangi bir URL, API anahtarını kullanabilirse auth_referrer_policy=origin'yı, Haritalar JavaScript API'sinden gelen istekler yetkilendirilirken gönderilen veri miktarını sınırlayacak şekilde ayarlayabilirsiniz. Bu özellik 3.46 sürümünden 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 mevcut web sitesinin alanıyla eşleşen ve yol belirtilmeyen bir HTTP yönlendiren kısıtlaması varsa yüklenebilir.

• map_ids: Harita kimliklerinin virgülle ayrılmış listesi. Belirtilen harita kimliklerinin yapılandırmasının önceden yüklenmesine neden olur. Harita kimliklerinin kullanımı için harita kimliklerinin burada belirtilmesi zorunlu değildir ancak ağ performansında hassas ayarlamalar yapmak isteyen geliştiriciler bu özelliği kullanabilir.

• channel: Kanal başına kullanım izleme bölümüne bakın.

NPM js-api-loader paketini kullanma

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

npm install @googlemaps/js-api-loader

Paketi burada gösterildiği gibi içe aktarın:

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

Yükleyici, kitaplıkları kullanılabilir hale getirmek için Promise'leri kullanır. Kitaplıkları importLibrary() yöntemini kullanarak yükleyin. Aşağıdaki örnekte, bir haritayı yüklemek için yükleyicinin kullanımı gösterilmektedir:

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

Tam örnek kodu inceleyin.

Dinamik Kitaplık İçe Aktarma API'sine geçiş yapma

Bu bölümde, entegrasyonunuzu Dinamik Kitaplık İçe Aktarma API'sini kullanacak şekilde taşımak için gereken adımlar açıklanmaktadır.

Taşıma adımları

İlk olarak, doğrudan komut dosyası yükleme etiketini satır içi bootstrap yükleyici etiketiyle değiştirin.

Önce

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&libraries=maps&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 olacak şekilde değiştirin.
• İhtiyacınız olan kitaplıkları yüklemek ve bunlara erişmek için importLibrary() işlevini çağırı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();

Birden fazla kitaplık yükleme

Birden fazla kitaplık yüklemek için Promise.all() kullanarak kitaplıkları paralel olarak isteyin ve döndürülen sınıfları yapılandırın:

const [{ Place }, { AdvancedMarkerElement }] = await Promise.all([
  google.maps.importLibrary('places'),
  google.maps.importLibrary('marker'),
]);

Ayrı await ifadelerini zincirleyerek kitaplıkları seri olarak yüklemeyin:

// Avoid loading libraries serially:
const { Place } = await google.maps.importLibrary('places');
const { AdvancedMarkerElement } = await google.maps.importLibrary('marker');

Her bir importLibrary() çağrısını birbiri ardına await, ikinci kitaplık isteği, ilk kitaplık tamamen indirilip başlatılana kadar başlamaz. Promise.all() kullanıldığında tüm kitaplık istekleri aynı anda başlatılır. Bu sayede ağ gecikmesi azalır ve başlatma hızı artar.