Genel bakış

Platform seçin: Android iOS JavaScript

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

Kitle

Bu belge, JavaScript programlama ve nesne odaklı programlama kavramlarına aşina olan kişiler için tasarlanmıştır. Ayrıca, Haritalar'a kullanıcı bakış açısıyla da aşina olmanız gerekir. Web'de birçok JavaScript eğiticisi bulunmaktadır.

Bu kavramsal belgeler, Maps JavaScript API ile uygulamaları keşfetmeye ve geliştirmeye hızlıca başlamanızı sağlamak için tasarlanmıştır. 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ği incelemektir. 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, unutulmaması gereken birkaç nokta vardır:

  1. <!DOCTYPE html> bildirimini kullanarak uygulamayı HTML5 olarak tanımlarız.
  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 önerilen yöntem önyükleyici yükleyicidir. Alternatif olarak JS API yükleyicisi de sağlanır. Her iki yaklaşımı da incelemenizi ve projenizdeki kodun yapılandırılma şekli için en uygun olanı seçmenizi öneririz.

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

Önyü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 await operatörünü kullanarak importLibrary() öğesini aşağıda gösterildiği gibi bir eşzamansız işlev içinden ç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

AİOY js-api-loader paketi

Maps JavaScript API'yi yüklemek amacıyla NPM'yi kullanmak için @googlemaps/js-api-loader etiketini 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ö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 etme

Web uygulamanızda gerçek bir DOCTYPE beyan etmenizi öneririz. Buradaki örneklerde, uygulamalarımızı aşağıda gösterildiği gibi basit HTML5 DOCTYPE ile HTML5 olarak beyan ettik:

<!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ı uyumluluğun daha yüksek olması gerektiği anlamına gelir. DOCTYPE, sorunsuz bir şekilde bozulacak şekilde tasarlanmıştır. Anlamayan tarayıcılar bunu yoksayar ve içeriklerini görüntülemek için "süslemeler modunu" kullanır.

Quirks modunda çalışan bazı CSS'lerin standartlar modunda geçerli olmadığını unutmayın. Spesifik olarak, yüzdeye dayalı tüm boyutların üst blok öğelerinden devralması 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ı ekliyoruz:

<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 özel olarak beyan etmemiz gerektiğini unutmayın.

Maps JavaScript API'yi yükleme

Maps JavaScript API, script etiketi kullanılarak yüklenir. Bu etiket, HTML dosyanıza satır içi olarak veya ayrı bir JavaScript dosyasıyla dinamik olarak 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&loading=async&callback=initMap">
</script>

Dinamik Yükleme

Maps JavaScript API'yi ayrı bir JavaScript dosyası kullanarak satır içinde dinamik olarak yüklemek için aşağıdaki örneğe bakın. Bu yaklaşım, API ile çalışmak için tüm kodunuzu ayrı bir .js dosyası kullanarak işlemenize 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 sunmak 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ö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 önerilen birkaç özelliğin ayarlandığına dikkat edin. Aşağıda her özelliğin açıklaması yer almaktadır.

  • src: Maps JavaScript API'yi kullanmak için ihtiyacınız olan tüm semboller ve tanımlarla birlikte 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 global bir 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 parametresini kullanarak 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ş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 bölümünü inceleyin.

Harita DOM Öğeleri

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

Haritanın bir web sayfasında görüntülenebilmesi için kendisine yer ayırtmamız gerekir. Genellikle bunu, adlandırılmış bir div öğesi oluşturarak ve tarayıcının belge nesne modelinden (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 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 kapsayıcı öğelerinden aldığını ve boş div'lerin genellikle 0 yüksekliğe sahip olduğunu unutmayın. Bu nedenle, yüksekliği her zaman <div> özelliğinde açıkça belirtmeniz gerekir.

Harita Seçenekleri

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

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

zoom: 8

Tüm Dünya'nın haritasını tek bir görüntü olarak sunmak, çok büyük bir harita veya çok düşük çözünürlüklü küçük bir harita gerektirir. Bunun sonucunda, Google Haritalar ve Maps JavaScript API'deki harita resimleri, harita "parçalarına" 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ı kapsar; daha yüksek yakınlaştırma düzeylerinde, 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 üç resimde, 0, 7 ve 18 yakınlaştırma düzeylerinde Tokyo ile aynı konumu yansıtmaktadır.

Maps JavaScript API'nin mevcut yakınlaştırma düzeyine göre kartları nasıl yüklediği hakkında bilgi edinmek için harita ve koordinat 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 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 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, kurucu olarak bilinir ve tanımı aşağıda gösterilmiştir:

Marka Açıklama
Map(mapDiv:Node, opts?:MapOptions ) İletilen (isteğe bağlı) parametreleri kullanarak, belirtilen HTML kapsayıcısı içinde (genellikle DIV öğesidir) yeni bir harita oluşturur.

Sorun giderme

API Anahtarı ve Faturalandırma Hataları

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

Haritalar kodunuzu hazır hale getirmenize yardımcı olmak için Brendan Kenny ve Mano Marks, bu videoda 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 doğrulayın.
    • Haritanın ekranda görüneceği bir div öğesi bildirdiğinizden emin olun.
    • Haritaya ilişkin div öğesinin bir yüksekliğe sahip olduğundan emin olun. Varsayılan olarak, div öğeleri 0 yüksekliğiyle oluşturulur ve bu nedenle görünmez.
    Referans uygulaması için örneklerimize bakın.
  • Sorunları tespit etmenize yardımcı olması için Chrome Geliştirici Araçları'nda bulunana benzer bir JavaScript hata ayıklayıcısı kullanın. İlk olarak, JavaScript konsolunda hata olup olmadığına bakın.
  • Sorularınızı Stack Overflow'da yayınlayın. Faydalı sorular yayınlamayla ilgili yönergeleri Destek sayfasında bulabilirsiniz.