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 kullanma
Dinamik Kitaplık İçe Aktarma özelliğini kullanma
Dinamik kitaplık içe aktarma, kitaplıkları çalışma zamanında yükleme olanağı sağlar. Bu sayede, gerekli kitaplıkları yükleme sırasında tek seferde değil, ihtiyaç duyduğunuz noktada isteyebilirsiniz. Ayrıca, sayfanızı Maps JavaScript API'nin birden çok kez yüklenmesine karşı 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.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>
Ayrıca, önyükleme yükleyici kodunu doğrudan JavaScript kodunuza da ekleyebilirsiniz.
Kitaplıkları çalışma zamanında yüklemek için await
operatörünü kullanarak async
işlevi içinden importLibrary()
işlevini çağırın. Gerekli sınıflar için değişkenler 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:
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();
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();
İşleviniz, gerekli sınıflar için bir değişken tanımlamadan da kitaplıklar yükleyebilir. Bu özellikle gmp-map
öğesini kullanarak bir harita eklediyseniz kullanışlıdır:
async function initMap() { google.maps.importLibrary("maps"); google.maps.importLibrary("marker"); } 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ı 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 kitaplıkları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, kontrollerin adlarını, telif hakkı bildirimlerini, yol tariflerini ve kontrol etiketlerini, ayrıca 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
: Haritalar JS müşterileri, belirli bir API anahtarının hangi URL'ler tarafından kullanılmasına izin verileceğini sınırlamak için Cloud Console'da HTTP Yönlendirici 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ındaki veya kaynaktaki herhangi bir URL API anahtarını kullanabiliyorsa Maps JavaScript API'den gelen isteklerin yetkilendirilmesi sırasında gönderilen veri miktarını sınırlamak içinauthReferrerPolicy: "origin"
ayarını yapabilirsiniz. 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 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ızlı bir şekilde çalışmaya başlamanıza yardımcı olmak için birçok örnek kod türü sağlar. Google, daha karmaşık kod örneklerimizin benimsenmesini izlemek ve çözüm kalitesini artırmak için örnek kodumuza API çağrılarınasolutionChannel
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üklenirken 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ı bir kerede 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ğı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 ele alınmaktadır.
Bazı parametreler zorunlu, bazıları ise isteğe bağlıdır. URL'lerde standart olarak olduğu gibi, tüm parametreler "ve" işareti (&
) 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"
®ion="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önlendirici 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ınload
etkinliği tarafından JavaScript kodunun tetiklenmediğini belirtmek içinasync
olarak ayarlanır. 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 yerinecallback
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 kitaplıklarının virgülle ayrılmış listesi.language
: Kullanılacak dil. Bu durum, kontrollerin adlarını, telif hakkı bildirimlerini, yol tariflerini ve kontrol etiketlerini, ayrıca 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ındaki veya kaynaktaki herhangi bir URL API anahtarını kullanabiliyorsa Maps JavaScript API'den gelen isteklerin yetkilendirilmesi sırasında gönderilen veri miktarını sınırlamak içinauth_referrer_policy=origin
ayarını yapabilirsiniz. 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 belirtilmemiş bir HTTP Yönlendiren Kısıtlaması varsa yüklenebilecek.mapIds
: Harita kimliklerinin virgülle ayrılmış listesi. Belirtilen harita kimliklerinin yapılandırmasını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ızlı bir şekilde ç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ı izlemek ve çözüm kalitesini artırmak için örnek kodumuzdaki API çağrılarınasolution_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. Aşağıdaki 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öntemi load()
'ün 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, }); });
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, }); });
js-api-loader içeren bir örneği inceleyin.
Aşağıdaki örnekte, kitaplıkları yüklemek için loader.importLibrary()
işlevinin nasıl kullanılacağı 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
});
Dinamik Kitaplık İçe Aktarma API'sine geçiş yapma
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.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>
Daha sonra, 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()
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();