Bu sayfa, Cloud Translation API ile çevrilmiştir.

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

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"
&region="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ına solution_channel sorgu parametresini ekler.

Not: Bu sorgu parametresi Google tarafından kullanılmak üzere kullanılır. Daha fazla bilgi için Google Haritalar Platformu çözümleri parametresine bakın.
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çin auth_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();