Bu kılavuzda, Maps JavaScript API'nin nasıl yükleneceği gösterilmektedir. Bunu yapmanın üç yolu vardır:
- Dinamik Kitaplık'tan İçe Aktarma'yı kullanın (Önerilir)
- NPM js-api-loader paketini kullanın
- Doğrudan komut dosyası yükleme etiketini kullanın.
Dinamik Kitaplık İçe Aktarma özelliğini kullanma
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>
Önyükleme 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 bir async
işlevi içinden importLibrary()
çağırmak üzere 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();
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ı 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 grubunun belirtilmesi genellikle önerilmez ancak web sitelerindeki önbelleğe alma davranışını ince bir şekilde ayarlamak isteyen geliştiriciler tarafından kullanılabilir.language
: Kullanılacak dil. Bu, kontrollerin adlarını, telif hakkı bildirimlerini, arabayla yol tariflerini ve kontrol etiketlerini ve hizmet isteklerine verilen yanıtları etkiler. Desteklenen dillerin listesini inceleyin.region
: Kullanılacak bölge kodu. Bu, haritanın belirli bir ülkeye veya bölgeye göre 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ı 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 istekleri yetkilendirirken gönderilen veri miktarını sınırlamak içinauthReferrerPolicy: "origin"
parametresini 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 geçerli web sitesinin alan adıyla eşleşen 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, kısa sürede çalışmaya başlamanız için birçok örnek kod türü sağlar. Google, daha karmaşık kod örneklerimizin benimsenme durumunu takip etmek ve çözüm kalitesini iyileştirmek için örnek kodumuzdaki API çağrılarınasolutionChannel
sorgu parametresini ekler.
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ğıdakilerle uygulamaya aktarılabilir:
import { Loader } from "@googlemaps/js-api-loader"
Yükleyici, Promise ve geri çağırma arayüzünü 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, }); });
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.
Aşağıdaki örnekte kitaplıkları yüklemek için loader.importLibrary()
kullanımı 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
});
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. Google, Dynamic Library Upload API'ye taşınmasını önerir.
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 açıklanmaktadı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, tüm olası parametreler için yer tutuculara sahiptir:
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
etiketinde bulunan 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 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 küresel işlevin adı.
İsteğe bağlı parametreler (doğrudan)
Belirli bir Haritalar JavaScript API sürümü istemek, ek kitaplıklar yüklemek, haritanızı yerelleştirmek veya HTTP yönlendirme 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 herhangi bir JavaScript kodunun tetiklenmediğini belirtmek içinasync
değerini ayarlayın. Performansı artırmak için mümkün olduğunda bu seçeneğinasync
olarak ayarlanması önemle tavsiye edilir. (Haritalar JavaScript API'si kullanıma sunulduğ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 küresel 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, hizmet isteklerine verilen yanıtların yanı sıra kontrollerin adlarını, telif hakkı bildirimlerini, arabayla yol tariflerini ve kontrol etiketlerini etkiler. Desteklenen dillerin listesini inceleyin.region
: Kullanılacak bölge kodu. Bu, haritanın belirli bir ülkeye veya bölgeye göre 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ı 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 istekleri yetkilendirirken gönderilen veri miktarını sınırlamak içinauth_referrer_policy=origin
parametresini 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 yol belirtilmeden mevcut web sitesinin alan adıyla eşleşen bir HTTP Yönlendiren Kısıtlaması varsa 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, kısa sürede çalışmaya başlamanız için birçok örnek kod türü sağlar. Google, daha karmaşık kod örneklerimizin benimsenme durumunu takip etmek ve çözüm kalitesini iyileştirmek için örnek kodumuzdaki API çağrılarınasolution_channel
sorgu parametresini ekler.
Dynamic Library Import API'sine taşıma
Bu bölümde, entegrasyonunuzu Dynamic Library Import API'yi kullanacak şekilde taşımak için gereken adımlar ele alınmaktadır.
Taşıma adımları
Öncelikle, 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&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()
fonksiyonunuzu 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();