Genel Bakış

Koleksiyonlar ile düzeninizi koruyun İçeriği tercihlerinize göre kaydedin ve kategorilere ayırın.
Platform seçin: Android iOS JavaScript

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;
index.ts

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

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

style.css

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>
index.html
Örneği göster

Örneği Deneyin

Bu basit örnekte bile dikkat edilmesi gereken birkaç nokta vardır:

  1. <!DOCTYPE html> beyanını kullanarak uygulamayı HTML5 olarak bildiriyoruz.
  2. Haritayı barındırmak için "map" adlı bir div öğesi oluştururuz.
  3. div içinde harita oluşturan bir JavaScript işlevi tanımlıyoruz.
  4. 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,
  });
});
index.ts

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

index.js

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ız key ve Maps JavaScript API tamamen yüklendikten sonra çağrılacak bir genel işlevin adını belirttiğiniz callback. 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 ve center ö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.
    Referans uygulama için örneklerimize bakın.
  • 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.