Genel bakış

Platform seçin: Android iOS JavaScript

Maps JavaScript API, web sayfalarında ve mobil cihazlarda görüntülenmek üzere kendi içeriğinizle ve görüntülerinizle haritaları özelleştirmenize olanak tanır. Maps JavaScript API, katmanları ve stilleri, kontrolleri, etkinlikleri, çeşitli hizmetleri ve kütüphaneleri kullanarak değiştirebileceğiniz dört temel harita türü (yol haritası, uydu, karma ve arazi) içerir.

Kitle

Bu doküman, JavaScript programlama ve nesne odaklı programlama kavramlarına aşina olan kişiler için tasarlanmıştır. Ayrıca kullanıcı bakış açısından Haritalar hakkında bilgi sahibi olmanız gerekir. Web'de birçok JavaScript eğiticisi bulunmaktadır.

Bu kavramsal belge, Maps JavaScript API ile uygulamaları keşfetmeye ve geliştirmeye hızla başlamanızı sağlamak 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 örneğe göz atmaktır. 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örüntüleyin

Örneği Deneyin

Bu basit örnekte bile, dikkat edilmesi gereken birkaç nokta var:

  1. <!DOCTYPE html> bildirimini kullanarak uygulamanın HTML5 olduğunu beyan ederiz.
  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ımlarız.
  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

Maps JavaScript API'yi yüklemek için önyükleme yükleyicisi önerilir. Alternatif olarak JS API yükleyicisi de sağlanır. Her iki yaklaşımı da incelemenizi ve projenizdeki kodun yapılandırma şekline en uygun olanı seçmenizi öneririz.

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

Önyükleme Yükleyici

Aşağıdaki snippet'te gösterildiği gibi, uygulama kodunuza bir 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",
    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 await operatörünü kullanarak aşağıda gösterildiği gibi, eşzamansız bir işlevden importLibrary() yöntemini çağırı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 amacıyla NPM'yi kullanmak için @googlemaps/js-api-loader kodunu kullanın. Aşağıdaki komutu kullanarak NPM üzerinden yükleyin:

npm install @googlemaps/js-api-loader

Bu paket, aşağıdakilerle uygulamaya aktarılabilir:

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

Yükleyici, Promise ve geri çağırma arayüzünü gösteriyor. 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 bildirin

Web uygulamanızda gerçek bir DOCTYPE belirtmenizi öneririz. Buradaki örneklerde, uygulamalarımızı basit HTML5 DOCTYPE ile aşağıda gösterildiği gibi 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, sorunsuz bir şekilde indirilecek şekilde tasarlanmıştır. Bunu anlamayan tarayıcılar bunu yok sayar ve içeriklerini görüntülemek için "süslemeler modunu" kullanır.

Tuhaflıklar modunda çalışan bazı CSS'lerin standartlar modunda geçerli olmadığını unutmayın. Özellikle, yüzdeye dayalı tüm boyutlar üst blok öğelerinden devralmalıdır 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 yüksekliğinin% 100'ünü kaplaması gerektiğini belirtir. Bu yüzdeleri de <body> ve <html> için de belirtmemiz gerektiğini unutmayın.

Maps JavaScript API yükleniyor

Maps JavaScript API, bir script etiketi kullanılarak yüklenir. Bu etiket, HTML dosyanıza satır içi olarak veya ayrı bir JavaScript dosyası kullanılarak dinamik bir şekilde eklenebilir. Her iki yaklaşımı da incelemenizi ve projenizdeki kodun yapılandırılma şekli için 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&callback=initMap">
</script>

Dinamik Yükleme

Maps JavaScript API'yi ayrı bir JavaScript dosyası kullanarak satır içi dinamik olarak yüklemek için aşağıdaki örneği inceleyin. Bu yaklaşım, API ile çalışmak için tüm kodunuzu ayrı bir .js dosyasından çalıştırmanıza olanak tanır ve komut dosyası etiketini satır içine 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 sağlamak için @googlemaps/js-api-loader paketi kullanılabilir. Aşağıdakilerle AİOY üzerinden yüklenebilir:

npm install @googlemaps/js-api-loader

Bu paket, aşağıdakilerle uygulamaya aktarılabilir:

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

Yükleyici, Promise ve geri çağırma arayüzünü gösteriyor. 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, önerilen birkaç özelliğin script etiketinde 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 semboller 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üklendikten sonra çağrılacak 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 çalıştırmasını ister. Komut dosyası çalıştırıldığında, 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 eşzamansız bir işlevden 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 özellikle istemedikçe yüklenmeyen kod modülleridir. Daha fazla bilgi için Haritalar JavaScript API'deki kitaplıklar konusuna bakın.

Harita DOM Öğeleri

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

Haritanın web sayfasında gösterilebilmesi için ona yer ayırtmamız gerekir. Genellikle bunu, 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 öğe, mobil cihazların boyutuna sığacak şekilde genişleyecektir. 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 kapsayıcı öğelerinden aldıklarını ve boş div'lerin genellikle 0 yüksekliğe sahip olduğunu unutmayın. Bu nedenle, <div> öğesinde her zaman açıkça 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 Düzeyleri

Haritanın görüntüleneceği ilk çözünürlük zoom özelliği tarafından belirlenir. Burada yakınlaştırma 0, Dünya haritasına tamamen uzaklaştırılmış, daha yüksek yakınlaştırma düzeyleri ise daha yüksek çözünürlükteki yakınlaştırmaya karşılık gelir.

zoom: 8

Tüm Dünya haritasını tek bir görüntü olarak sunmak çok büyük bir harita veya çok düşük çözünürlüğe sahip küçük bir harita gerektirir. Bunun sonucunda, Google Haritalar ve Maps JavaScript API'deki harita resimleri, harita "parçaları" ve "zum seviyeleri"ne bölünür. Düşük yakınlaştırma düzeylerinde, küçük bir dizi harita karosu geniş bir alanı kaplar; daha yüksek yakınlaştırma düzeylerinde ise karolar daha yüksek çözünürlüğe sahiptir 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 üç resim, Tokyo ile aynı konumu 0, 7 ve 18 yakınlaştırma düzeylerinde yansıtmaktadır.

Maps JavaScript API'nin mevcut yakınlaştırma düzeyine göre karoları nasıl yüklediği hakkında bilgi edinmek için harita ve parça koordinatları kılavuzunu inceleyin.

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 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ştururuz.

Yeni bir harita örneği oluşturduğunuzda, sayfada harita için kapsayıcı olarak bir <div> HTML öğesi belirtirsiniz. HTML düğümleri, JavaScript document nesnesinin alt öğeleridir ve document.getElementById() yöntemi aracılığıyla bu öğeye bir referans elde ederiz.

Bu kod map adlı bir değişken tanımlar ve bu 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ı) parametreyi kullanarak, belirli bir HTML kapsayıcısı içinde (genellikle bir DIV öğesidir) yeni bir harita oluşturur.

Sorun giderme

API Anahtarı ve Faturalandırma Hataları

Belirli durumlarda, karartılmış bir harita veya "yalnızca geliştirme amaçlı" metnini içeren "negatif" bir Street View resmi görüntülenebilir. Bu davranış genellikle bir API anahtarı veya faturalandırma ile ilgili sorunları gösterir. Google Haritalar Platformu ürünlerini kullanmak 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:

Bu videoda, harita kodunuzu hazırlayıp çalıştırmanıza yardımcı olmak için Brendan Kenny ve Mano Marks, bazı yaygın hatalardan ve bunların nasıl düzeltileceğini ele alıyor.

  • 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 sırasında 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.
    • Haritaya ait div öğesinin bir yüksekliğe sahip olduğundan emin olun. Varsayılan olarak, div öğeleri 0 yüksekliğinde oluşturulur ve bu nedenle görünmez.
    Referans uygulaması için örneklerimize bakın.
  • Sorunların tanımlanmasına yardımcı olması için Chrome Geliştirici Araçları'nda bulunan gibi bir JavaScript hata ayıklayıcısı kullanın. İlk olarak JavaScript konsolunda hatalar olup olmadığını kontrol edin.
  • Sorularınızı Stack Overflow'da yayınlayın. Doğru soruları nasıl yayınlayacağınızla ilgili yönergeleri Destek sayfasında bulabilirsiniz.