Bu kılavuzda, Maps JavaScript API'nin nasıl yükleneceği gösterilmektedir. Bunu yapmanın üç yolu vardır:
- Dinamik Kitaplık İçe Aktarma'yı kullanın (Önerilir)
- NPM js-api-loader paketini kullanın
- Eski komut dosyası yükleme etiketini kullanma
Dinamik Kitaplık İç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>
Bootstrap yükleyici kodunu doğrudan JavaScript kodunuza da ekleyebilirsiniz.
Kitaplıkları çalışma zamanında yüklemek için aşağıdaki kod örneğinde gösterildiği gibi await
operatörünü bir async
işlevi içinden importLibrary()
çağırmak için 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();
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();
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ü.libraries
: Yüklenecek ek Maps JavaScript API kitaplarının virgülle ayrılmış listesi. Sabit bir kitaplık grubu belirtilmesi genellikle önerilmez. Ancak bu özellik, web sitelerindeki önbelleğe alma davranışını hassas bir şekilde ayarlamak isteyen geliştiriciler tarafından kullanılabilir.language
: Kullanılacak dil. Bu durum; kontrollerin adlarını, telif hakkı bildirimlerini, arabayla yol tariflerini ve kontrol etiketlerini ve hizmet isteklerine verilen yanıtları etkiler. Desteklenen dillerin listesine bakın.region
: Kullanılacak bölge kodu. Bu işlem, haritanın davranışını belirli bir ülkeye veya bölgeye göre değiştirir.solutionChannel
: Google Haritalar Platformu, hemen kullanmaya 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 iyileştirmek için örnek kodumuzdaki API çağrılarınasolutionChannel
sorgu parametresini ekler.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ı yapılandırabilir. Bu kısıtlamalar, varsayılan olarak yalnızca belirli yolların bir 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 istekleri yetkilendirirken gönderilen veri miktarını sınırlamak içinauthReferrerPolicy: "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, yol belirtilmeden mevcut web sitesinin alan adıyla eşleşen bir HTTP Yönlendiren Kısıtlaması varsa yüklenebilir.
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, uygulamaya şunlarla aktarılabilir:
import { Loader } from "@googlemaps/js-api-loader"
Yükleyici, Promise ve geri çağırma arayüzünü görüntülüyor. 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, }); });
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'ın kullanıldığı bir örneğe bakın.
Eski komut dosyası yükleme etiketini kullan
Eski komut dosyası yükleme etiketi hâlâ desteklenmektedir. Bu bölüm, eski komut dosyası yükleme etiketini kullanan entegrasyonları desteklemek için sağlanmıştır. Google, Dynamic Library Yükleme API'ye taşınmayı teşvik eder.
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&callback=initMap">
</script>
Eski komut dosyası yükleme URL'si 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 zorunluyken, bazıları 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, olası tüm parametreler için yer tutuculara sahiptir:
https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY
&callback=FUNCTION_NAME
&v=VERSION
&libraries="LIBRARIES"
&language="LANGUAGE"
®ion="REGION"
&solution_channel="SOLUTION_IDENTIFIER"
&auth_referrer_policy="AUTH_REFERRER_POLICY"
Aşağıdaki örnek script
etiketinde bulunan 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'yi yüklerken aşağıdaki parametreler gerekir.
key
: API anahtarınız. Geçerli bir API anahtarı belirtilmediği sürece Maps JavaScript API yüklenmez.callback
: Maps JavaScript API tamamen yüklendikten sonra çağrılacak global işlevin adı.
İsteğe bağlı parametreler (eski)
Belirli bir Maps JavaScript API 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
v
: Kullanılacak Maps JavaScript API sürümü.libraries
: Yüklenecek ek Maps JavaScript API kitaplarının virgülle ayrılmış listesi.language
: Kullanılacak dil. Bu durum, hizmet isteklerine verilen yanıtların yanı sıra kontrollerin adlarını, telif hakkı bildirimlerini, arabayla yol tariflerini ve kontrol etiketlerini etkiler. Desteklenen dillerin listesine bakın.region
: Kullanılacak bölge kodu. Bu işlem, haritanın davranışını belirli bir ülkeye veya bölgeye göre değiştirir.solution_channel
: Google Haritalar Platformu, hemen kullanmaya 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 iyileştirmek için örnek kodumuzdaki API çağrılarınasolution_channel
sorgu parametresini ekler.auth_referrer_policy
: 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ı yapılandırabilir. Bu kısıtlamalar, varsayılan olarak yalnızca belirli yolların bir 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 istekleri yetkilendirirken gönderilen veri miktarını sınırlamak içinauth_referrer_policy=origin
değerini 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ı varsa yüklenebilir.
Dynamic Library Import API'ye geçiş yapın
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, eski 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&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>
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 bu kitaplıklara 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();