Maps JavaScript API, web sayfalarında ve mobil cihazlarda görüntülenmek üzere haritaları kendi içeriğinizle ve görüntülerinizle özelleştirmenize olanak tanır. Maps JavaScript API'de dört temel harita türü (yol haritası, uydu, karma ve arazi) bulunur. Katmanlar ve stiller, denetimler ve etkinliklerin yanı sıra çeşitli hizmetleri ve kitaplıkları kullanarak bunları değiştirebilirsiniz.
Kitle
Bu belge, JavaScript programlama ve nesne odaklı programlama kavramlarına aşina olan kişiler için tasarlanmıştır. Ayrıca Haritalar'ı kullanıcının bakış açısından da öğrenmelisiniz. Web'de pek çok JavaScript eğiticisi vardır.
Kavramsal bu belge, Maps JavaScript API ile uygulamaları hemen keşfetmeye ve geliştirmeye başlayabilmeniz için tasarlanmıştır. Ayrıca, Haritalar JavaScript API Referansı'nı da yayınlıyoruz.
Merhaba Dünya
Maps JavaScript API hakkında bilgi edinmeye başlamanın en kolay yolu basit bir örnek görmektir. Aşağıdaki örnekte, Sidney, New South Wales, Avustralya merkezli bir harita gösterilmektedir.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();
CSS
/* * Always set the map height explicitly to define the size of the div element * that contains the map. */ #map { height: 100%; } /* * Optional: Makes the sample page fill the window. */ html, body { height: 100%; margin: 0; padding: 0; }
HTML
<html> <head> <title>Simple Map</title> <link rel="stylesheet" type="text/css" href="./style.css" /> <script type="module" src="./index.js"></script> </head> <body> <div id="map"></div> <!-- prettier-ignore --> <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: "AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg", v: "weekly"});</script> </body> </html>
Örneği Deneyin
Bu basit örnekte bile unutulmaması gereken birkaç nokta var:
<!DOCTYPE html>
beyanını kullanarak uygulamayı HTML5 olarak tanımlarız.- Haritayı tutmak için "harita" adlı bir
div
öğesi oluştururuz. div
içinde harita oluşturan bir JavaScript işlevi tanımlıyoruz.- Maps JavaScript API'yi önyükleme yükleyicisini kullanarak yükleriz.
Bu adımlar aşağıda açıklanmıştır.
Maps JavaScript API'yi yükleme
Bootstrap yükleyici, Maps JavaScript API'yi yüklemek için önerilen yöntemdir. Alternatif olarak JS API yükleyicisi de sağlanır. Her iki yaklaşımı da incelemenizi ve projenizdeki kodun nasıl yapılandırıldığına en uygun olanı seçmenizi öneririz.
Daha fazla bilgi için Haritalar JavaScript API'yi yükleme bölümüne bakın.
Önyükleme Bantlı Yükleyici
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>
Kitaplıkları çalışma zamanında yüklemek için aşağıda gösterildiği gibi eşzamansız bir işlev içinden importLibrary()
işlevini çağırmak için 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();
NPM js-api-loader paketi
Maps JavaScript API'yi yüklemek üzere NPM'yi kullanmak için @googlemaps/js-api-loader adresini kullanın. Aşağıdaki komutu kullanarak NPM üzerinden yükleyin:
npm install @googlemaps/js-api-loader
Bu paket, uygulamaya şunlarla 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ö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, }); });
Uygulamanızı HTML5 olarak beyan edin
Web uygulamanızda gerçek bir DOCTYPE
tanımlamanızı öneririz. Buradaki örneklerde, aşağıda gösterildiği gibi basit HTML5 kullanarak DOCTYPE
uygulamalarımızı HTML5 olarak açıkladık:
<!DOCTYPE html>
Mevcut tarayıcıların çoğu, bu DOCTYPE
ile tanımlanan içeriği "standartlar modunda" oluşturur. Bu, uygulamanızın tarayıcılar arası daha uyumlu olması gerektiği anlamına gelir. DOCTYPE
, aynı zamanda sorunsuz bir şekilde küçültülecek şekilde tasarlanmıştır. Bunu anlamayan tarayıcılar bunu yoksayar ve içeriklerini görüntülemek için "Quirks modunu" kullanır.
Quirks modunda çalışan bazı CSS'lerin standartlar modunda geçerli olmadığını unutmayın. Özellikle, yüzdeye dayalı tüm boyutların üst blok öğelerinden devralınması gerekir ve bu üst öğelerden herhangi biri boyut belirtemezse boyutlarının 0 x 0 piksel olduğu varsayılır. Bu nedenle aşağıdaki <style>
beyanını ekleriz:
<style> #map { height: 100%; } html, body { height: 100%; margin: 0; padding: 0; } </style>
Bu CSS bildirimi, <div>
harita kapsayıcısının (map
kimliğine sahip), HTML gövdesinin% 100'ünü kaplaması gerektiğini belirtir. Bu yüzdelerin <body>
ve <html>
için de özel olarak beyan edilmesi gerektiğini unutmayın.
Maps JavaScript API yükleniyor
Maps JavaScript API, HTML dosyanızın satır içine veya ayrı bir JavaScript dosyası kullanılarak dinamik olarak eklenebilecek birscript
etiketi kullanılarak yüklenir. Her iki yaklaşımı da incelemenizi ve projenizdeki kodun nasıl yapılandırıldığına en uygun olanı seçmenizi öneririz.
Satır İçi Yükleme
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>
Dinamik Yükleme
Maps JavaScript API'yi ayrı bir JavaScript dosyası kullanarak satır içinde dinamik bir şekilde yüklemek için aşağıdaki örneği inceleyin. Bu yaklaşım, API ile çalışırken ayrı bir .js
dosyasından tüm kodunuzu işlemenize olanak tanır ve komut dosyası etiketini satır içi olarak eklemeye eşdeğerdir.
// Create the script tag, set the appropriate attributes var script = document.createElement('script'); script.src = 'https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap'; script.async = true; // Attach your callback function to the `window` object window.initMap = function() { // JS API is loaded and available }; // Append the 'script' element to 'head' document.head.appendChild(script);
Dinamik Yükleme
Daha sorunsuz bir dinamik yükleme deneyimi sunmak için @googlemaps/js-api-loader paketi sunulmaktadır. NPM üzerinden aşağıdaki yöntemlerle yüklenebilir:
npm install @googlemaps/js-api-loader
Bu paket, uygulamaya şunlarla 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ö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, }); });
Komut Dosyası Etiketi Özellikleri
Yukarıdaki örneklerde, script
etiketinde, önerilen bazı özelliklerin ayarlandığına dikkat edin. Aşağıda her bir özelliğin açıklaması verilmiştir.
src
: Maps JavaScript API'yi kullanmak için ihtiyacınız olan tüm simgeler ve tanımlar dahil olmak üzere Maps JavaScript API'nin yüklendiği URL. Bu örnekteki URL'nin iki parametresi vardır: API anahtarınızı sağladığınızkey
ve Maps JavaScript API tamamen yüklendiğinde çağrılacak genel işlevin adını belirttiğinizcallback
. URL parametreleri hakkında daha fazla bilgi edinin.async
: Tarayıcıdan komut dosyasını eşzamansız olarak indirmesini ve çalıştırmasını ister. Komut dosyası yürütüldüğünde,callback
parametresi kullanılarak belirtilen işlevi çağırır.
Kütüphaneler
Maps JavaScript API'yi URL üzerinden yüklerken isteğe bağlı olarak, eşzamansız bir işlev içinden importLibrary()
çağrısı yapmak için await
operatörünü kullanarak ek kitaplıklar yükleyebilirsiniz. Kitaplıklar, ana Maps JavaScript API'ye ek işlevler sağlayan, ancak siz özel olarak istekte bulunmadıkça yüklenmeyen kod modülleridir. Daha fazla bilgi için
Haritalar JavaScript API'deki kitaplıklar bölümünü inceleyin.
Harita DOM Öğeleri
<div id="map"></div>
Haritanın bir web sayfasında görüntülenebilmesi için, söz konusu sayfada yer ayırmamız gerekir.
Genellikle bu işlemi, adlandırılmış bir div
öğesi oluşturarak ve tarayıcının belge nesne modelinde (DOM) bu öğeye referans alarak yaparız.
Yukarıdaki örnekte, harita div öğesinin yüksekliğini "%100" olarak ayarlamak için CSS kullandık. Bu boyut, mobil cihazlardaki boyuta sığacak şekilde genişler. Genişlik ve yükseklik değerlerini, tarayıcının ekran boyutuna ve dolgusuna göre ayarlamanız gerekebilir. Div'lerin genellikle genişliklerini içeren öğeden aldığını ve boş div'lerin yüksekliğinin genellikle 0 olduğunu unutmayın. Bu nedenle, <div>
için her zaman açıkça bir yükseklik ayarlamanız gerekir.
Harita Seçenekleri
Her harita için gerekli iki seçenek vardır: center
ve zoom
.
map = new Map(document.getElementById('map'), { center: {lat: -34.397, lng: 150.644}, zoom: 8 });
Yakınlaştırma Düzeyleri
Haritanın görüntüleneceği ilk çözünürlük zoom
özelliği tarafından ayarlanır. Burada yakınlaştırma 0
, Dünya haritasının tamamen uzaklaştırılmasına karşılık gelir ve daha yüksek yakınlaştırma düzeyleri daha yüksek çözünürlükte yakınlaştırılır.
zoom: 8
Tüm Dünya'nın haritasını tek bir görüntü olarak sunmak, devasa bir harita veya çok düşük çözünürlüklü küçük bir harita gerektirir. Sonuç olarak, Google Haritalar ve Maps JavaScript API'deki harita resimleri, harita "karoları" ve "yakınlaştırma düzeyleri"ne ayrılır. Düşük yakınlaştırma düzeylerinde, küçük bir harita deseni grubu geniş bir alanı kapsar; daha yüksek yakınlaştırma düzeylerinde, karolar daha yüksek çözünürlükte olur ve daha küçük bir alanı kaplar. Aşağıdaki listede, her bir yakınlaştırma düzeyinde görmeyi bekleyebileceğiniz yaklaşık ayrıntı düzeyi gösterilmektedir:
- 1: Dünya
- 5: Karalar/kıta
- 10: Şehir
- 15: Sokaklar
- 20: Binalar
Aşağıdaki üç resimde, 0, 7 ve 18 yakınlaştırma düzeylerinde Tokyo'nun aynı konumu yansıtılmaktadır.
Maps JavaScript API'nin mevcut yakınlaştırma seviyesine göre karoları nasıl yüklediği hakkında bilgi edinmek için harita ve parça koordinatları kılavuzuna bakın.
Harita Nesnesi
map = new Map(document.getElementById("map"), {...});
Bir haritayı temsil eden JavaScript sınıfı, Map
sınıfıdır.
Bu sınıfın nesneleri bir sayfadaki tek bir haritayı tanımlar. (Bu sınıfın birden fazla örneğini oluşturabilirsiniz. Her nesne sayfada ayrı bir harita tanımlar.) JavaScript new
operatörünü kullanarak bu sınıfın yeni bir örneğini oluştururuz.
Yeni bir harita örneği oluşturduğunuzda, sayfada eşleme için kapsayıcı olarak bir <div>
HTML öğesi belirtirsiniz. HTML düğümleri, JavaScript document
nesnesinin alt öğeleridir ve bu öğeye document.getElementById()
yöntemi aracılığıyla başvuru alırız.
Bu kod map
adında bir değişken tanımlar ve söz konusu değişkeni yeni bir Map
nesnesine atar. Map()
işlevi, oluşturucu olarak bilinir ve tanımı aşağıda gösterilmiştir:
Marka | Açıklama |
---|---|
Map(mapDiv:Node, opts?:MapOptions
) |
İletilen herhangi bir (isteğe bağlı) parametreleri kullanarak belirtilen HTML kapsayıcısının içinde yeni bir harita oluşturur (bu genellikle bir DIV öğesidir). |
Sorun giderme
API Anahtarı ve Faturalandırma Hataları
Belirli koşullar altında, "yalnızca geliştirme amaçlı" metniyle filigran eklenmiş koyu renkli bir harita veya "negatif" Street View resmi görüntülenebilir. Bu davranış genellikle bir API anahtarı veya faturalandırma ile ilgili sorunlar olduğunu gösterir. Google Haritalar Platformu ürünlerini kullanabilmeniz için hesabınızda faturalandırmanın etkinleştirilmiş olması ve tüm isteklerin geçerli bir API anahtarı içermesi gerekir. Aşağıdaki akış, bu sorunu gidermenize yardımcı olacaktır:
Kodunuz çalışmıyorsa:
Brendan Kenny ve Mano Marks, harita kodunuzu çalışır duruma getirmenize yardımcı olmak için sık yapılan bazı hatalardan ve bunları nasıl düzeltebileceğinizden bahsediyor.
- Yazım hatalarını arayın. JavaScript'in büyük/küçük harfe duyarlı bir dil olduğunu unutmayın.
- Temel bilgileri kontrol edin. En yaygın sorunlardan bazıları ilk harita oluşturma işleminde ortaya çıkar. Örneğin:
- Harita seçeneklerinizde
zoom
vecenter
özelliklerini belirttiğinizi onaylayın. - Haritanın ekranda görüneceği bir div öğesi bildirdiğinizden emin olun.
- Haritanın div öğesinin bir yüksekliği olduğundan emin olun. Varsayılan olarak, div öğeleri 0 yüksekliğinde oluşturulur ve bu nedenle görünmezdir.
- Harita seçeneklerinizde
- Sorunları belirlemenize yardımcı olması için Chrome Geliştirici Araçları'nda bulunan gibi bir JavaScript hata ayıklayıcı kullanın. İlk olarak JavaScript konsolunda hatalara bakın.
- Soruları Stack Overflow'da yayınlayın. Etkili sorular yayınlamayla ilgili yönergeleri Destek sayfasında bulabilirsiniz.