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 aktarmayı kullanma
• Doğrudan komut dosyası yükleme etiketini kullanın
• NPM js-api-loader paketini kullanın.

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

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

Aşağıdaki snippet'te gösterildiği gibi, uygulama kodunuza satır içi önyükleme yükleyicisini 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.>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 await operatörünü kullanarak aşağıdaki kod örneğinde gösterildiği gibi, bir async işlevi içinden importLibrary() işlevini çağırın:

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

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

gmp-map öğesini kullanarak bir harita eklediyseniz initMap() işleviniz gerekli sınıflar için bir değişken bildirmeden kitaplıkları yükleyebilir:

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

initMap();

Alternatif olarak, kitaplıkları aşağıda gösterildiği gibi doğrudan HTML'de de 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ı belirtilmedikçe Maps JavaScript API yüklenmez.

İsteğe bağlı parametreler

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

• libraries: Yüklenecek ek Maps JavaScript API kitaplarının virgülle ayrılmış listesi. Sabit bir kitaplık grubu belirtilmesi genellikle önerilmez ancak web sitelerindeki önbelleğe alma davranışında ince ayar yapmak isteyen geliştiriciler tarafından kullanılabilir.

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

• region: Kullanılacak bölge kodu. Bu, belirli bir ülke veya bölgeye göre haritanın davranışını 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 adı veya kaynaktaki herhangi bir URL API Anahtarını kullanabiliyorsa Maps JavaScript API'den gelen istekleri yetkilendirirken gönderilen veri miktarını sınırlamak için authReferrerPolicy: "origin" öğesini ayarlayabilirsiniz. Cloud Console'da bu parametre belirtildiğinde ve HTTP Yönlendiren Kısıtlamaları etkinleştirildiğinde Maps JavaScript API yalnızca mevcut web sitesinin alan adıyla eşleşen ve yol belirtilmemiş bir HTTP Yönlendiren Kısıtlaması varsa yüklenebilir.

• mapIds: Harita kimlikleri dizisi. Belirtilen harita kimlikleri için yapılandırmanın önceden yüklenmesine neden olur.

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

• solutionChannel: Google Haritalar Platformu, hızla çalışmaya başlamanıza yardımcı olmak için birçok örnek kod türü sunar. Google, daha karmaşık kod örneklerimizin benimsenmesini izlemek ve çözüm kalitesini artırmak için örnek kodumuza API çağrılarına solutionChannel sorgu parametresini ekler.

Doğrudan komut dosyası yükleme etiketini kullanın

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ğinden, ç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. Ancak bu etiketi sayfa yükleme başına yalnızca bir kez eklemeye dikkat edin.

Komut dosyası etiketi ekleyin

Maps JavaScript API'yi bir HTML dosyasında satır içi olarak 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&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 anlatılmaktadır. Bazı parametreler zorunlu, bazıları ise isteğe bağlıdır. URL'lerde standart 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 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)

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)

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 stratejisidir. Maps JavaScript API'nin eşzamanlı olarak yüklenmediğini ve komut dosyasının load etkinliği tarafından hiçbir JavaScript kodunun tetiklenmediğini belirtmek için async değerine ayarlayın. Performansı artırmak için mümkün olduğunda bu ayarı async olarak ayarlamanız önemle tavsiye edilir. (Haritalar JavaScript API'si kullanılabilir olduğunda işlem gerçekleştirmek için bunun yerine callback parametresini kullanın.) 3.55 sürümünden itibaren kullanılabilir.

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

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

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

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

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

• auth_referrer_policy: Müşteriler, 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 adı veya kaynaktaki herhangi bir URL API Anahtarını kullanabiliyorsa Maps JavaScript API'den gelen istekleri yetkilendirirken gönderilen veri miktarını sınırlamak için auth_referrer_policy=origin öğesini ayarlayabilirsiniz. Bu özellik 3.46 sürümünden itibaren kullanılabilir. Cloud Console'da bu parametre belirtildiğinde ve HTTP Yönlendiren Kısıtlamaları etkinleştirildiğinde Maps JavaScript API yalnızca yol belirtilmeden mevcut web sitesinin alan adıyla eşleşen bir HTTP Yönlendiren Kısıtlaması olduğunda yüklenebilir.

• mapIds: Harita kimliklerinin virgülle ayrılmış listesi. Belirtilen harita kimlikleri için yapılandırmanın önceden yüklenmesine neden olur.

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

• solution_channel: Google Haritalar Platformu, hızla çalışmaya başlamanıza yardımcı olmak için birçok örnek kod türü sunar. Google, daha karmaşık kod örneklerimizin benimsenmesini izlemek ve çözüm kalitesini artırmak için örnek kodumuza API çağrılarına solution_channel sorgu parametresini ekler.

NPM js-api-loader paketini kullanma

NPM paket yöneticisi aracılığıyla yükleme için @googlemaps/js-api-loader paketi kullanılabilir. Şu komutu kullanarak yükleyin:

npm install @googlemaps/js-api-loader

Bu paket, uygulamaya şunlarla aktarılabilir:

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

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

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

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 içeren bir örneği inceleyin.

Aşağıdaki örnekte kitaplıkları yüklemek için loader.importLibrary() yönteminin nasıl kullanıldığı gösterilmektedir:

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

loader
  .importLibrary('maps')
  .then(({Map}) => {
    new Map(document.getElementById("map"), mapOptions);
  })
  .catch((e) => {
    // do something
});

Dynamic Library Import API'ye geçme

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ı

İlk olarak, doğrudan komut dosyası yükleme etiketini satır içi önyükleme 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.>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>

Daha sonra, 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() 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();