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 İç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();
index.ts

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();
index.js

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çin authReferrerPolicy: "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ına solutionChannel 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,
  });
});
index.ts

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,
  });
});

index.js

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"
&region="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ın load etkinliği tarafından herhangi bir JavaScript kodunun tetiklenmediğini belirtmek için async değerini ayarlayın. Performansı artırmak için mümkün olduğunda bu seçeneğin async olarak ayarlanması önemle tavsiye edilir. (Haritalar JavaScript API'si kullanıma sunulduğ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 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çin auth_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ına solution_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();