Maps JavaScript API'yi Yükleme

Bu kılavuzda, Maps JavaScript API'nin nasıl yükleneceği gösterilmektedir. Orada Bunu yapmanın üç yolu vardır:

• Dinamik kitaplık aktarma özelliğini kullanın
• 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ı aynı anda birden fazla olmamalıdır. Ayrıca, sayfanızın Maps JavaScript API'yi birden fazla kez kullanın.

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>

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

Kitaplıkları çalışma zamanında yüklemek için bir async işlevi içinden importLibrary()'ı çağırmak üzere await operatörünü kullanı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:

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

İşleviniz, değişken bildirmeden de kitaplıkları yükleyebilir Bu, özellikle gmp-map öğe:

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çeceğinizi öğrenin.

Gerekli parametreler

• key: API anahtarınız. Maps JavaScript API yüklenmez.

İsteğe bağlı parametreler

• v: Uygulamanın sürümü Maps JavaScript API yüklenecek.

• libraries: Yüklenecek ek Maps JavaScript API kitaplıklarının virgülle ayrılmış listesi. Bir sabit kitaplık grubu genellikle önerilmez ancak web sitelerindeki önbelleğe alma davranışında ince ayar yapmak isteyen geliştiriciler.

• language: Kullanılacak dil. Bu, kontrollerin, telif hakkı bildirimlerini, arabayla yol tariflerinin ve ve hizmet isteklerine verilen yanıtları kontrol edebilirsiniz. Bkz. desteklenen dillerin listesini inceleyin.

• region: Bölge kod yazın. Bu, haritanın davranışını belirli bir ülkeye veya bölgeye göre değiştirir.

• authReferrerPolicy: Haritalar JS müşterileri HTTP Yönlendiren'i yapılandırabilir Cloud Console'da özel API anahtarı. 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çin authReferrerPolicy: "origin" ayarını yapabilirsiniz. Zaman Bu parametre belirtilir ve HTTP Yönlendiren Kısıtlamaları Cloud Console, Maps JavaScript API yalnızca HTTP Yönlendiren Kısıtlaması varsa Mevcut web sitesinin alan adıyla eşleşen ve yol belirtilmemiş.

• 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 birçok örnek kod türü sunar hızlı bir şekilde çalışmaya başlamanıza yardımcı olur. Daha karmaşık ve çözüm kalitesini artırmak için Google’a Örnek kodumuzdaki API çağrılarındaki solutionChannel sorgu parametresi.

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, istenen tüm kitaplıkları komut dosyası yüklendikten sonra performans bazı izin verir. Doğrudan komut dosyası yükleme etiketini sayfa yükleme başına yalnızca bir kez ekleyin.

Komut dosyası etiketi ekleyin

Maps JavaScript API'yi bir HTML dosyasında satır içi olarak yüklemek için script etiketine sahip olmalıdır.

<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. Bu programda standart olduğu gibi URL'ler varsa tüm parametreler "ve" (&) karakteri kullanılarak ayrılır.

Aşağıdaki örnek URL'de olası tüm parametreler için yer tutucular vardı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 için bu parametreleri kullanın. ek kitaplıklar yükleyin, haritanızı yerelleştirin veya HTTP yönlendiren kontrolünü belirtin politika

• 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 JavaScript kodunun tetiklenmediğini belirtmek için async olarak ayarlanır. Performansı artırmak için mümkün olduğunda bu ayarı async olarak ayarlamanız önemle tavsiye edilir. (Maps JavaScript API kullanılabilirken işlem yapmak için bunun yerine callback parametresini kullanın.) 3.55 sürümünden itibaren kullanılabilir.

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

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

• libraries: Ek Maps JavaScript API'nin virgülle ayrılmış listesi kitaplıkların yüklenmesi.

• language: Kullanılacak dil pek de iyi olmadığını unutmayın. Bu, kontrollerin, telif hakkı bildirimlerini, arabayla yol tariflerinin ve ve kontrol etiketlerinin yanı sıra hizmet isteklerine verilen yanıtları içerir. Bkz. desteklenen dillerin listesini inceleyin.

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

• auth_referrer_policy: Müşteriler, 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önlendiren Kısıtlamaları'nı yapılandırabilir. Varsayılan olarak bu kısıtlamalar yalnızca belirli yollarda API anahtarı kullanılır. Aynı alan adında veya kaynakta yer alan herhangi bir URL API Anahtarını kullanabilirse, auth_referrer_policy=origin Maps JavaScript API'den gelen istekler yetkilendirilirken gönderilen veri miktarı. 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 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ızlı bir şekilde çalışmaya başlamanıza yardımcı olmak için birçok örnek kod türü sağlar. Daha karmaşık ve çözüm kalitesini artırmak için Google’a Örnek kodumuzdaki API çağrılarındaki solution_channel sorgu parametresi.

NPM js-api-loader paketini kullanma

NPM paket yöneticisi aracılığıyla yüklemek 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 aşağıdakilerle içe 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.

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'ın kullanıldığı 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
});

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

Bu bölümde, dinamik bir şekilde içe aktarma API'sini kullanabilirsiniz.

Taşıma adımları

İlk olarak, doğrudan komut dosyası yükleme etiketini satır içi önyükleme yükleyiciyle değiştirin kapanış etiketinin hemen öncesine yapıştırın.

Ö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();