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, web sayfalarında ve mobil cihazlarda görüntülenmek üzere haritaları kendi içeriğiniz ve görüntülerinizle özelleştirmenizi sağlar. Maps JavaScript API'de dört temel harita türü (yol haritası, uydu, karma ve arazi) bulunur. Bu harita türlerini katmanlar ve stiller, kontroller ve etkinlikler ile çeşitli hizmetler ve kitaplıklar kullanarak değiştirebilirsiniz.

Kitle

Bu dokümanlar, JavaScript programlama ve nesne odaklı programlama kavramlarına aşina olan kişiler 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 eğiticileri bulabilirsiniz.

Bu kavramsal doküman, Maps JavaScript API ile uygulamaları keşfetmeye ve geliştirmeye hızlıca başlamak için tasarlanmıştır. Ayrıca Maps JavaScript API Referansı 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, New South Wales, 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 göster

Örneği Dene

Bu basit örnekte bile dikkate almanız gereken birkaç nokta vardır:

  1. <!DOCTYPE html> beyanını kullanarak uygulamayı HTML5 olarak açıklarız.
  2. Haritayı barındırmak için"map&quot"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 DOCTYPE belirtmenizi öneririz. Buradaki örneklerimizde uygulamalarımızı aşağıda gösterildiği gibi basit HTML5 kullanarak DOCTYPE HTML5 olarak tanımladık:

<!DOCTYPE html>

Mevcut tarayıcıların çoğu, bu DOCTYPE ile tanımlanan içerikleri"standartlar modunda"oluşturur. Bu da uygulamanızın tarayıcılar arası uyumluluğun daha yüksek olması gerektiği anlamına gelir. DOCTYPE ayrıca zarif bir şekilde aşağı indirilecek şekilde tasarlanmıştır. Anlamayan tarayıcılar bunu göz ardı eder ve içeriklerini görüntülemek için"tuhaf mod"kullanır.

Süslemeler modunda çalışan bazı CSS'lerin standart modda geçerli olmadığını unutmayın. Spesifik olarak, yüzdeye dayalı tüm boyutların üst blok öğelerinden devralınması gerekir. Bu üst öğelerin herhangi biri bir boyut belirtemezse 0 x 0 piksel boyutunda 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> (map kimliğine sahip) harita kapsayıcısının, 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

Maps JavaScript API, HTML dosyanıza satır içinde veya dinamik olarak ayrı bir JavaScript dosyası kullanılarak eklenebilen bir script etiketi kullanılarak yüklenir. Her iki yaklaşımı da incelemenizi ve projenizdeki kodun yapısına en uygun olan yaklaşımı seçmenizi öneririz.

Satır İçi Yükleme

Maps JavaScript API'yi satır içi bir HTML dosyasında 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 dinamik olarak yüklemek için aşağıdaki örneğe bakın. Bu yaklaşım, ayrı bir .js dosyasından API ile çalışmak için tüm kodunuzu yönetmenize 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 sağlamak için @googlemaps/js-api-loader paketi kullanılabilir. NPM aracılığıyla şu yöntemlerle yüklenebilir:

npm install @googlemaps/js-api-loader

Bu paket, uygulamayla şunlara 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 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. Bunlar önerilir. Aşağıda her özelliğin açıklaması verilmiştir.

  • src: Maps JavaScript API'nin yüklendiği URL (Haritalar JavaScript API'sini kullanmak için ihtiyacınız olan tüm simgeler ve tanımlar dahil). Bu örnekteki URL'de iki parametre vardır: API anahtarınızı sağladığınız key ve Haritalar JavaScript API'si tamamen yüklendikten sonra çağrılacak bir global işlevin adını 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 parametresini kullanarak belirtilen işlevi çağırır.

Kütüphaneler

Maps JavaScript API'yi URL yoluyla 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 kod modülleridir ancak özel olarak istenmedikçe yüklenmez. Daha fazla bilgi için Haritalar JavaScript API'sindeki kitaplıklar bölümüne bakın.

API'yi eşzamanlı olarak yükleme

Maps JavaScript API'yi yükleyen script etiketinde, defer ve callback parametresini çıkarabilirsiniz. Bu durum, API indirilene kadar API'nin yüklenmesini engeller.

Bu durum, sayfa yüklemeyi yavaşlatabilir. Ancak bu, API'nin zaten yüklenmiş olduğunu varsayarak sonraki komut dosyası etiketlerini yazabileceğiniz anlamına gelir.

Harita DOM Öğeleri

<div id="map"></div>

Haritanın bir web sayfasında gösterilebilmesi için harita üzerinde bir yer ayırmamız gerekir. Bunu yapmak için genellikle adlandırılmış bir div öğesi oluşturur ve tarayıcının doküman nesnesi modelinde (DOM) bu öğeye bir referans alırız.

Yukarıdaki örnekte, harita div'in yüksekliğini "%100" olarak ayarlamak için CSS'yi kullandık. Bu boyut, mobil cihazlardaki boyuta uyacak şekilde genişletilir. Genişlik ve yükseklik değerlerini tarayıcının ekran boyutuna ve dolgusuna göre ayarlamanız gerekebilir. Div'lerin genişliklerini genellikle içerdikleri öğeden aldığını ve boş div'lerin genellikle 0 yüksekliğine sahip olduğunu unutmayın. Bu nedenle, her zaman <div> özelliğinde açıkça bir yükseklik ayarlamanız gerekir.

Harita Seçenekleri

Her harita için zorunlu iki seçenek vardır: 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

Haritayı görüntüleyeceğiniz ilk çözünürlük, zoom özelliği tarafından belirlenir. Burada zoom haritası, yakınlaştırılan Dünya 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ılır.

zoom: 8

Tüm Dünya'nın haritasını tek bir resim olarak sunmak için muazzam bir harita ya da çok düşük çözünürlüklü küçük bir harita gerekir. Sonuç olarak, Google Haritalar ve Maps JavaScript API'deki harita görüntüleri, harita "karolar" ve "yakınlaştırma düzeyleri"ne ayrılmıştır. Düşük yakınlaştırma düzeylerinde, harita döşemelerinin küçük bir alanı geniş bir alanı kapsar; daha yüksek yakınlaştırma düzeylerinde ise parçalar daha yüksek çözünürlüktedir ve daha küçük bir alanı kapsar. Aşağıdaki listede, her yakınlaştırma düzeyinde görmeyi bekleyebileceğiniz yaklaşık ayrıntı düzeyi gösterilmektedir:

  • 1: Dünya
  • 5: Kara parçası/kıta
  • 10: Şehir
  • 15: Sokaklar
  • 20: Binalar

Aşağıdaki üç resim, 0, 7 ve 18 yakınlaştırma düzeylerinde Tokyo'nun aynı konumunu yansıtmaktadır.

Maps JavaScript API'nin karoları mevcut yakınlaştırma düzeyine göre nasıl yüklediğiyle ilgili bilgi için harita ve karo koordinatları kılavuzuna bakın.

Harita Nesnesi

map = new google.maps.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 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, harita için kapsayıcı olarak sayfada bir <div> HTML öğesi belirtirsiniz. HTML düğümleri, JavaScript document nesnesinin alt öğeleridir ve bu yönteme document.getElementById() yöntemi aracılığıyla referans verilir.

Bu kod, bir değişken (map adlı) 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 gösterilmiş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 (genellikle DIV öğesidir).

Sorun giderme

API Anahtarı ve Faturalandırma Hataları

Bazı durumlarda, yalnızca geliştirme amacıyla "filigranlı" ve koyu renk olan bir Street View resmi gösterilebilir. Bu davranış genellikle API anahtarı veya faturalandırmayla ilgili sorunları gösterir. Google Haritalar Platformu ürünlerini kullanmak 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ı olur:

Kodunuz çalışmıyorsa:

Brenda Kenny ve Mano Marks, harita kodunuzu oluşturup çalıştırmanıza yardımcı olmak için bu videoda bazı yaygın hatalara ve hataların nasıl düzeltileceğine işaret ediyor.

  • Yazım hatası 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 yaygın sorunlardan bazıları, ilk harita oluşturma işlemiyle ilgilidir. Örneğin:
    • Harita seçeneklerinizde zoom ve center özelliklerini belirttiğinizden emin olun.
    • Haritanın ekranda görüneceği bir div öğesi belirttiğinizden emin olun.
    • Harita için div öğesinin yüksekliğinin yüksek olduğundan emin olun. Varsayılan olarak, div öğeleri 0 yüksekliğinde oluşturulur ve dolayısıyla görünmez.
    Referans uygulaması için örneklerimize bakın.
  • Chrome Geliştirici Araçları'nda bulunanlara benzer sorunları tanımlamak için JavaScript hata ayıklayıcısını kullanın. Hataları, JavaScript konsolunda inceleyerek başlayın.
  • Soruları Stack Overflow'da yayınlayın. Faydalı soruların nasıl yayınlanacağıyla ilgili kuralları Destek sayfasında bulabilirsiniz.