Genel Bakış

Platformu seçin: Android iOS JavaScript

Maps JavaScript API, haritaları kendi içerikleriniz ve resimlerinizle web sayfalarında ve mobil cihazlarda görüntülemek üzere özelleştirmenize olanak tanır. Maps JavaScript API'de katmanlar ve stiller, kontroller ve etkinlikler ile çeşitli hizmetler ve kitaplıkları kullanarak değiştirebileceğiniz dört temel harita türü (yol haritası, uydu, karma ve arazi) bulunur.

Kitle

Bu dokümanlar, JavaScript programlama ve nesne odaklı programlama kavramlarına aşina olan kullanıcılar için tasarlanmıştır. Kullanıcının bakış açısından Haritalar ile ilgili bilgi de edinmelisiniz. Web'de JavaScript eğiticileri bulabilirsiniz.

Bu kavramsal belge, Maps JavaScript API ile uygulamaları hızlı bir şekilde keşfetmeye ve geliştirmeye başlamanıza yardımcı olmak için tasarlanmıştır. Ayrıca, Haritalar 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;
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>
    <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>

    <!-- 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 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 tanımlarız.
  2. Haritayı bekletmek 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 önyükleme yükleyicisini kullanarak yüklüyoruz.

Bu adımlar aşağıda açıklanmıştır.

Maps JavaScript API'yi yükleme

Önyükleme yükleyicisi, Maps JavaScript API'yi yüklemenin önerilen yoludur. JS API yükleyicisi, bunun yerine alternatif olarak da sunulur. Her iki yaklaşımı da incelemenizi ve projenizdeki kodun nasıl yapılandırılacağına en uygun yaklaşımı seçmenizi öneririz.

Daha fazla bilgi için Haritalar JavaScript API'sini yükleme bölümüne bakın.

Önyükleme Yükleyici

Aşağıdaki snippet'te gösterildiği gibi, uygulama kodunuza satır içi önyükleme yükleyicisi 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_HERE",
    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>

Çalışma zamanında kitaplıkları yüklemek için importLibrary() işlevini bir eşzamansız işlev içinden aşağıdaki gibi çağırarak 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

Haritalar JavaScript API'sini yüklemek amacıyla NPM'yi kullanmak için @googlemaps/js-api-loader'ı kullanın. Aşağıdaki komutu kullanarak uygulamayı NPM üzerinden yükleyin:

npm install @googlemaps/js-api-loader

Bu paket, aşağıdaki yöntemlerle uygulamaya aktarılabilir:

import { Loader } from "@googlemaps/js-api-loader"

Yükleyici, bir söz 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 bildirme

Web uygulamanızda doğru bir DOCTYPE bildirmenizi öneririz. Buradaki örneklerde, basit HTML5 DOCTYPE kullanarak uygulamalarımızı aşağıda gösterildiği gibi HTML5 olarak tanımladık:

<!DOCTYPE html>

Mevcut tarayıcıların çoğu, bu DOCTYPE ile tanımlanan içerikleri "standart modda" oluşturacak. Bu da uygulamanızın tarayıcılar arası uyumluluğa sahip olması gerektiği anlamına geliyor. DOCTYPE, zarif bir şekilde küçültmek için de tasarlanmıştır. Bunu anlamayan tarayıcılar bunu göz ardı eder 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. Özel olarak, 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> açıklamasını ekliyoruz:

<style>
  #map {
    height: 100%;
  }
  html, body {
    height: 100%;
    margin: 0;
    padding: 0;
  }
</style>

Bu CSS beyanı, <div> harita haritasının (map kimlikli) HTML gövdesinin yüksekliğinin% 100'ünü kaplaması gerektiğini gösterir. 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 ayrı bir JavaScript dosyası kullanılarak dinamik olarak eklenebilen bir script etiketi kullanılarak yüklenir. 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ı içine 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ını kullanarak Maps JavaScript API'yi 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 yönetmenize 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 ve dinamik bir yükleme deneyimi için @googlemaps/js-api-loader paketini kullanabilirsiniz. NPM aracılığıyla şu şekilde yüklenebilir:

npm install @googlemaps/js-api-loader

Bu paket, aşağıdaki yöntemlerle uygulamaya aktarılabilir:

import { Loader } from "@googlemaps/js-api-loader"

Yükleyici, bir söz 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ı Etiket Ö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 kullanmak 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 Haritalar JavaScript API'si tamamen yüklendikten sonra çağrılacak bir global 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 parametresini kullanarak belirtilen işlevi çağırır.

Kütüphaneler

Maps JavaScript API'yi URL aracılığıyla yüklerken isteğe bağlı olarak importLibrary() işlevini bir eşzamansız işlev içinden çağırmak için await operatörünü kullanarak ek kitaplıklar yükleyebilirsiniz. Kitaplıklar, ana Maps JavaScript API'ye ek işlev sağlayan kod modülleridir ancak özel olarak istekte bulunmadığınız sürece yüklenmez. Daha fazla bilgi için Haritalar JavaScript API'sinde kitaplıklar bölümüne bakın.

DOM Öğelerini Eşle

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

Haritanın bir web sayfasında görüntülenmesi için harita üzerinde bir yer ayırmamız gerekir. Genellikle bunu, adlandırılmış div öğesi oluşturup tarayıcının belge nesne modelinde (DOM) bu öğeye bir referans alarak yaparız.

Yukarıdaki örnekte, harita div yüksekliğini "%100" olarak ayarlamak için CSS kullandık. Bu işlemin kapsamı, 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. Genellikle div öğelerinin genişliklerini kapsayıcı öğelerinden aldıklarını, boş div öğelerinin ise genellikle 0 yüksekliğinde olduklarını unutmayın. Bu nedenle, <div> üzerinde her zaman açık bir yükseklik ayarlamanız gerekir.

Harita Seçenekleri

Her harita için iki zorunlu 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 Seviyeleri

Haritayı görüntülemek için kullanılacak ilk çözünürlük zoom özelliği tarafından belirlenir. Yakınlaştırma 0 Dünya'nın tamamen uzaklaştırma yapılmış bir haritasına karşılık gelir. Daha büyük yakınlaştırma düzeyleri daha yüksek bir çözünürlükte yakınlaştırır.

zoom: 8

Tüm Dünya'ya ait bir haritayı tek bir resim olarak sunmak için büyük bir harita veya düşük çözünürlüklü çok küçük bir harita gerekir. Sonuç olarak, Google Haritalar ve Maps JavaScript API içindeki harita görüntüleri harita "parçaları" ve "yakınlaştırma düzeyleri"ne ayrılır. Düşük yakınlaştırma düzeylerinde, küçük bir harita parçası grubu 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: Karalar/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ı geçerli yakınlaştırma düzeyine göre nasıl yüklediği hakkında bilgi için harita ve karo koordinatları kılavuzuna bakın.

Harita Nesnesi

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

Bu kod, bir değişkeni (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 herhangi bir (isteğe bağlı) parametreyi kullanarak, belirtilen HTML kapsayıcısının içinde yeni bir harita oluşturur (genellikle DIV öğesidir).

Sorun giderme

API Anahtarı ve Faturalandırma Hataları

Belirli koşullarda, "yalnızca geliştirme amaçlı" filigranına sahip koyu renkli bir harita veya "negatif" Street View görüntüsü gösterilebilir. Bu davranış genellikle bir API anahtarı veya faturalandırmayla ilgili sorunları 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 oluşturup çalıştırmanıza yardımcı olmak için bu videoda sık yapılan bazı hatalardan ve bu hataların nasıl düzeltileceğinden bahsediyor.

  • Yazım hatası olup olmadığına bakın. JavaScript'in büyük/küçük harfe duyarlı bir dil olduğunu unutmayın.
  • Temel noktaları inceleyin. En yaygın sorunlardan bazıları ilk harita oluşturma sırasında ortaya çıkar. Örneğin:
    • Harita seçeneklerinizde zoom ve center özelliklerini belirttiğinizi onaylayın.
    • Haritanın ekranda gösterileceği bir div öğesi belirttiğinizden emin olun.
    • Harita için 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 örneklerimize bakın.
  • JavaScript hata ayıklayıcısını kullanarak Chrome Geliştirici Araçları'ndakiler gibi sorunları tespit edebilirsiniz. JavaScript konsolunda hata olup olmadığını inceleyerek başlayın.
  • Sorularınızı Stack Overflow'da yayınlayın. Mükemmel soruları yayınlamayla ilgili kuralları Destek sayfasında bulabilirsiniz.