Maps JavaScript API, haritaları web içeriğinizde ve mobil cihazlarınızda görüntülenecek kendi içeriğiniz ve resimlerinizle özelleştirmenizi sağlar. Maps JavaScript API'de dört temel harita türü (yol haritası, uydu, karma ve arazi) bulunur. Haritalar, katmanlar ve stiller, denetimler, etkinlikler ve çeşitli hizmet ve kitaplıkları kullanabilirsiniz.
Kitle
Bu doküman, JavaScript programlama ve nesne odaklı programlama kavramlarına aşina olan kullanıcılar için tasarlanmıştır. Ayrıca kullanıcının bakış açısından Google Haritalar'a da aşina olmanız gerekir. Web'de JavaScript öğreticilerini bulabilirsiniz.
Bu kavramsal belge, Maps JavaScript API ile uygulamaları hızlı bir şekilde keşfetmeye ve geliştirmeye başlamanıza olanak sağlamak için tasarlanmıştır. Ayrıca, Maps JavaScript API Referansı'nı da yayınladık.
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, Yeni Güney Galler, Avustralya merkezli bir harita gösterilmektedir.TypeScript
let map: google.maps.Map; function initMap(): void { map = new google.maps.Map(document.getElementById("map") as HTMLElement, { center: { lat: -34.397, lng: 150.644 }, zoom: 8, }); } declare global { interface Window { initMap: () => void; } } window.initMap = initMap;
JavaScript
let map; function initMap() { map = new google.maps.Map(document.getElementById("map"), { center: { lat: -34.397, lng: 150.644 }, zoom: 8, }); } window.initMap = 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> <script src="https://polyfill.io/v3/polyfill.min.js?features=default"></script> <link rel="stylesheet" type="text/css" href="./style.css" /> <script type="module" src="./index.js"></script> </head> <body> <div id="map"></div> <!-- The `defer` attribute causes the callback to execute after the full HTML document has been parsed. For non-blocking uses, avoiding race conditions, and consistent behavior across browsers, consider loading using Promises with https://www.npmjs.com/package/@googlemaps/js-api-loader. --> <script src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initMap&v=weekly" defer ></script> </body> </html>
Örneği Deneyin
Bu basit örnekte bile dikkat edilmesi gereken birkaç nokta vardır:
<!DOCTYPE html>
beyanını kullanarak uygulamayı HTML5 olarak bildiriyoruz.- Haritayı barındırmak için "map" adlı bir
div
öğesi oluştururuz. div
içinde harita oluşturan bir JavaScript işlevi tanımlıyoruz.- Maps JavaScript API'yi
script
etiketi kullanarak yüklüyoruz.
Bu adımlar aşağıda açıklanmıştır.
Uygulamanızı HTML5 olarak tanımlama
Web uygulamanızda doğru bir DOCTYPE
bildirmenizi öneririz. Buradaki örneklerde, basit HTML5 DOCTYPE
ile uygulamalarımızı aşağıda gösterildiği gibi HTML5 olarak tanımladık:
<!DOCTYPE html>
Çoğu tarayıcı, bu DOCTYPE
özelliği ile tanımlanan içeriği "standart modda" oluşturur. Bu da uygulamanızın tarayıcılar arası uyumlu olduğu anlamına gelir. DOCTYPE
de düzgün bir şekilde bozulacak şekilde tasarlanmıştır. Anlayamayan tarayıcılar bunu görmezden gelir ve içeriklerini görüntülemek için "süslemeler modunu" kullanır.
Sıra dışı modda çalışan bazı CSS'lerin, standart modda geçerli olmadığını unutmayın. Daha açık belirtmek gerekirse, yüzdeye dayalı tüm boyutların üst blok öğelerinden devralınması gerekir ve bu üst öğelerden herhangi biri boyut belirtemezse 0 x 0 piksel boyutunda olduğu varsayılır. Bu nedenle aşağıdaki <style>
beyanını dahil ediyoruz:
<style> #map { height: 100%; } html, body { height: 100%; margin: 0; padding: 0; } </style>
Bu CSS bildirimi, <div>
kapsayıcısının (map
kimliğine sahip) HTML gövdesinin yüksekliğinin% 100'ünü kaplaması gerektiğini belirtir. Bu yüzdeleri <body>
ve <html>
için de özel olarak açıklamamız gerektiğini unutmayın.
Maps JavaScript API yükleniyor
Haritalar JavaScript API'si,script
dosyası kullanılarak yüklenir. Bu etiket, HTML dosyanıza satır içinde veya dinamik olarak ayrı bir JavaScript dosyası kullanılarak eklenebilir. Her iki yaklaşımı da incelemenizi ve projenizdeki kodun nasıl yapılandırılacağına en uygun yaklaşımı seçmenizi öneririz.
Satır İçi Yükleme
Maps JavaScript API'yi HTML dosyasına 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>
Dinamik Yükleme
Ayrı bir JavaScript dosyası kullanarak Maps JavaScript API'yi satır içinde dinamik olarak yüklemek için aşağıdaki örneği inceleyin. Bu yaklaşım, ayrı bir .js
dosyasından API ile çalışmak için tüm kodunuzu ele almanıza olanak tanır ve komut dosyası etiketini satır içi olarak eklemenin eşdeğeridir.
// 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 mevcuttur. Aşağıdakiler, NPM aracılığıyla yüklenebilir:
npm install @googlemaps/js-api-loader
Bu paket aşağıdaki uygulamalarla uygulamaya aktarılabilir:
import { Loader } from "@googlemaps/js-api-loader"
Yükleyici bir Taahhüt ve geri çağırma arayüzünü gösterir. Aşağıda, varsayılan Taahhüt yönteminin (load()
) kullanımı gösterilmektedir.
TypeScript
const loader = new Loader({ apiKey: "YOUR_API_KEY", version: "weekly", ...additionalOptions, }); loader.load().then(() => { map = new google.maps.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(() => { map = new google.maps.Map(document.getElementById("map"), { center: { lat: -34.397, lng: 150.644 }, zoom: 8, }); });
Komut Dosyası Etiketi Özellikleri
Yukarıdaki örneklerde, script
etiketinde birkaç özelliğin ayarlandığına dikkat edin. Aşağıda her özelliğin bir açıklaması verilmiştir.
src
: Maps JavaScript API'yi yüklemek için ihtiyaç duyduğunuz tüm simgeler ve tanımlar dahil olmak üzere Maps JavaScript API'nin yüklendiği URL. Bu örnekteki URL'de iki parametre vardır: API anahtarınızı sağladığınızkey
ve Maps JavaScript API tamamen yüklendikten sonra çağrılacak bir 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 yürütmesini ister. Komut dosyası yürütüldüğünde,callback
parametresi kullanılarak belirtilen işlevi çağırır.
Kütüphaneler
URL ile Maps JavaScript API'yi yüklerken, isteğe bağlı olarak libraries
URL parametresi aracılığıyla ek kitaplıklar yükleyebilirsiniz. Kitaplıklar, ana Maps JavaScript API'ye ek işlev sağlayan ancak özellikle istekte bulunmadığınız sürece yüklenmeyen kod modülleridir. Daha fazla bilgi için Haritalar JavaScript API'sindeki Kitaplıklar bölümüne bakın.
API eşzamanlı olarak yükleniyor
Maps JavaScript API'yi yükleyen script
etiketinde defer
özelliği ve callback
parametresi çıkarılabilir. Bu işlem, API indirilene kadar API'nin yüklenmesini engeller.
Bu muhtemelen sayfa yüklemenizi yavaşlatır. Ancak bu, API'nin zaten yüklendiği varsayılarak sonraki komut dosyası etiketlerini yazabileceğiniz anlamına gelir.
DOM Öğelerini Eşle
<div id="map"></div>
Haritanın bir web sayfasında gösterilebilmesi için bu yerin ayırtılması gerekir.
Bunu genellikle, adlandırılmış bir div
öğesi oluşturup tarayıcının belge nesne modelinde (DOM) bu öğeye bir referans alarak yaparız.
Yukarıdaki örnekte, harita div'in yüksekliğini "%100" olarak ayarlamak için CSS kullanılmıştır. Bu boyut, mobil cihazlardaki boyuta sığacak şekilde genişletilir. Genişlik ve yükseklik değerlerini tarayıcının ekran boyutuna ve dolgusuna göre ayarlamanız gerekebilir. Div seçeneklerinin genellikle içerdikleri öğeden genişliklerini, boş div öğelerinin ise genellikle 0 yüksekliğinde olduklarını unutmayın. Bu nedenle, <div>
bölümünde her zaman açık bir şekilde yükseklik ayarlamanız gerekir.
Harita Seçenekleri
Her harita için iki zorunlu seçenek bulunur: center
ve
zoom
.
map = new google.maps.Map(document.getElementById('map'), { center: {lat: -34.397, lng: 150.644}, zoom: 8 });
Yakınlaştırma Seviyeleri
Haritanın gösterileceği ilk çözünürlük, zoom
özelliği tarafından belirlenir. Yakınlaştırma 0
Dünya'nın tam olarak uzaklaştırılmış bir haritasına karşılık gelir ve daha büyük yakınlaştırma seviyeleri daha yüksek bir çözünürlükte yakınlaştırır.
zoom: 8
Tüm dünyadaki bir haritayı tek bir resim olarak sunmak için büyük bir harita veya çok düşük çözünürlüklü küçük bir harita gerekir. Bunun sonucunda, Google Haritalar ve Maps JavaScript API içindeki harita resimleri harita "parçaları" ve "yakınlaştırma düzeyleri"ne ayrılmıştır. Düşük yakınlaştırma düzeylerinde, küçük bir harita parçası grubu geniş bir alanı kaplar. Daha yüksek yakınlaştırma düzeylerinde ise karolar daha yüksek çözünürlüktedir 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 gösterilmektedir.
Maps JavaScript API'nin karoları mevcut yakınlaştırma düzeyine göre nasıl yüklediği hakkında bilgi edinmek için harita ve karo koordinatları kılavuzuna bakın.
Harita Nesnesi
map = new google.maps.Map(document.getElementById("map"), {...});
Haritayı temsil eden JavaScript sınıfı Map
sınıfıdır.
Bu sınıfın nesneleri bir sayfada tek bir harita 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şturuyoruz.
Yeni bir harita örneği oluşturduğunuzda, sayfada <div>
kapsayıcısı için harita için bir kapsayıcı olarak belirtirsiniz. HTML düğümleri, JavaScript document
nesnesinin alt öğeleridir. Bu yönteme document.getElementById()
yöntemi aracılığıyla referans verilir.
Bu kod, map
adlı bir değişken tanımlar ve bu değişkeni yeni bir Map
nesnesine atar. Map()
işlevi, yapıcı olarak bilinir ve tanımı aşağıda verilmiştir:
Marka | Açıklama |
---|---|
Map(mapDiv:Node, opts?:MapOptions
) |
Geçirilen (isteğe bağlı) parametreleri kullanarak belirli bir HTML kapsayıcısının içinde yeni bir harita oluşturur. Bu genellikle DIV öğesidir. |
Sorun giderme
API Anahtarı ve Faturalandırma Hataları
Bazı durumlarda, "yalnızca geliştirme amaçlı" filigranına sahip karanlık bir harita veya "negatif" Street View resmi gösterilebilir. Bu davranış genellikle API anahtarı veya faturalandırmayla ilgili sorunları gösterir. Google Haritalar Platformu ürünlerini kullanabilmek için hesabınızda faturalandırmanın etkin 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 hazırlayıp çalışır hale getirmenize yardımcı olmak için bu videoda sık karşılaşılan bazı hatalara ve hataların nasıl düzeltileceğine odaklanıyor.
- Yazım hataları olup olmadığına bakın. JavaScript'in büyük/küçük harfe duyarlı bir dil olduğunu unutmayın.
- Temel bilgileri kontrol edin. En sık karşılaşılan sorunlardan bazıları ilk harita oluşturma sırasında ortaya çıkar. Örneğin:
- Harita seçeneklerinizde
zoom
vecenter
özelliklerini belirttiğinizden emin olun. - Haritanın ekranda görüneceği bir div öğesi bildirdiğinizden emin olun.
- Haritaya ait 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ünmez.
- Harita seçeneklerinizde
- Sorunların tespit edilmesine yardımcı olması için Chrome Geliştirici Araçları'nda bulunan gibi bir JavaScript hata ayıklayıcısı kullanın. JavaScript konsolunda hatalara bakarak başlayın.
- Soruları Stack Overflow'da yayınlayın. Mükemmel soruları nasıl yayınlayacağınızla ilgili yönergeleri Destek sayfasında bulabilirsiniz.