Genel bakış

Platform seçin: Android iOS JavaScript

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();
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

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>

    <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>
index.html
Örneği inceleyin

Örneği Deneyin

Bu basit örnekte bile unutulmaması gereken birkaç nokta var:

  1. <!DOCTYPE html> beyanını kullanarak uygulamayı HTML5 olarak tanımlarız.
  2. Haritayı tutmak için "harita" 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 ö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();
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

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

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

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ız key ve Maps JavaScript API tamamen yüklendiğinde çağrılacak 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 ç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 ve center ö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.
    Referans uygulama için örneklerimize bakın.
  • 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.