Places UI Kit: Geliştiricilere özelleştirme ve kontrol imkanı sunan, kullanıma hazır bir kitaplıktır. Deneyin ve kullanıcı arayüzü kiti deneyiminizle ilgili görüşlerinizi paylaşın.

Bu sayfa, Cloud Translation API ile çevrilmiştir.

JavaScript kullanarak işaretçi içeren bir Google Haritası ekleme

Giriş

Bu eğiticide, HTML, CSS ve JavaScript kullanarak bir web sayfasına işaretçili Google Haritası ekleme işlemi gösterilmektedir. Ayrıca, harita seçeneklerini ayarlama ve haritaya etiket eklemek için kontrol yuvalarını kullanma hakkında bilgi verir.

Aşağıda, bu eğitimi kullanarak oluşturacağınız harita yer almaktadır. İşaretçi, Uluru-Kata Tjuta Ulusal Parkı'ndaki Uluru'da (Ayers Kayası olarak da bilinir) bulunur.

Başlarken

Web sayfanızda işaretçi içeren bir Google Haritası oluşturmak için üç adım vardır:

API anahtarı alma
HTML sayfası oluşturma
İşaretçi içeren bir harita ekleme

Web tarayıcınız olmalıdır. Desteklenen tarayıcılar listesinden platformunuza göre Google Chrome (önerilir), Firefox, Safari veya Edge gibi bilinen bir tarayıcıyı seçin.

1. adım: API anahtarı alın

Bu bölümde, kendi API anahtarınızı kullanarak uygulamanızın Maps JavaScript API'de nasıl kimlik doğrulaması yapılacağı açıklanmaktadır.

API anahtarı almak için aşağıdaki adımları uygulayın:

Google Cloud Console'a gidin.
Proje oluşturun veya seçin.
API'yi ve ilgili hizmetleri etkinleştirmek için Devam'ı tıklayın.
Kimlik bilgileri sayfasında bir API anahtarı alın (ve API anahtarı kısıtlamalarını ayarlayın). Not: Kısıtlanmamış mevcut bir API anahtarınız veya tarayıcı kısıtlamaları olan bir anahtarınız varsa bu anahtarı kullanabilirsiniz.
Kota hırsızlığını önlemek ve API anahtarınızın güvenliğini sağlamak için API anahtarlarını kullanma başlıklı makaleyi inceleyin.
Faturalamayı etkinleştirin. Daha fazla bilgi için Kullanım ve Faturalandırma bölümüne bakın.

API anahtarı aldıktan sonra "YOUR_API_KEY"yi tıklayarak aşağıdaki snippet'e ekleyin. Kendi web sayfanızda kullanmak için önyükleyici betik etiketini kopyalayıp yapıştırın.

<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>

2. adım: HTML sayfası oluşturun

Temel bir HTML web sayfasının kodu aşağıda verilmiştir:

<!DOCTYPE html>
<!--
 @license
 Copyright 2025 Google LLC. All Rights Reserved.
 SPDX-License-Identifier: Apache-2.0
-->

<html>
  <head>
    <title>Add a Map</title>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
    <!-- 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: "YOUR_API_KEY", v: "weekly"});</script>
  </head>
  <body>

    <!-- The map, centered at Uluru, Australia. -->
    <gmp-map center="-25.344,131.031" zoom="4" map-id="DEMO_MAP_ID">
    </gmp-map>

  </body>
</html>

Bu, sayfada harita göstermek için gmp-map öğesini kullanan çok basit bir HTML sayfasıdır. Henüz JavaScript kodu eklemediğimiz için harita boş olacaktır.

Kodu anlama

Örnekte bu aşamada şunlar var:

Uygulamayı !DOCTYPE html bildirimini kullanarak HTML5 olarak bildirdim.
Maps JavaScript API'yi bootstrap yükleyiciyi kullanarak yüklediyseniz.
Haritayı tutacak bir gmp-map öğesi oluşturuldu.

Uygulamanızı HTML5 olarak beyan etme

Web uygulamanızda doğru bir DOCTYPE beyan etmenizi öneririz. Buradaki örneklerde, uygulamalarımızı aşağıdaki gibi HTML5 DOCTYPE kullanarak HTML5 olarak bildirdik:

<!DOCTYPE html>

Güncel tarayıcıların çoğu, bu DOCTYPE ile bildirilen içeriği "standart modda" işler; bu da uygulamanızın tarayıcılar arası daha uyumlu olması gerektiği anlamına gelir. DOCTYPE, sorunsuz bir şekilde bozulacak şekilde de tasarlanmıştır. Bu öğeyi anlamayan tarayıcılar, içeriğini görüntülemek için "uyumsuzluk modu"nu kullanarak öğeyi yoksayar.

Uyumluluk modunda çalışan bazı CSS'lerin standartlar modunda geçerli olmadığını unutmayın. Özellikle, yüzdeye dayalı tüm boyutlar ana blok öğelerinden miras alınmalıdır ve bu atalardan herhangi biri bir boyut belirtmeyi başaramazsa, 0 x 0 piksel boyutunda oldukları varsayılır. Bu nedenle, aşağıdaki style beyanını ekliyoruz:

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

Maps JavaScript API'yi yükleme

Önyükleme yükleyicisi, Maps JavaScript API'sini yüklemeye hazırlar (importLibrary() çağrılana kadar hiçbir kitaplık yüklenmez).

<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>

Kendi API anahtarınızı alma talimatları için 3. adım: API anahtarı alın başlıklı makaleyi inceleyin.

Eğitimin bu aşamasında, yalnızca biçimlendirilmemiş etiket metnini gösteren boş bir pencere görünür. Bunun nedeni henüz herhangi bir JavaScript kodu eklememiş olmamızdır.

`gmp-map` öğesi oluşturma

Haritanın bir web sayfasında gösterilmesi için harita için yer ayırmamız gerekir. Genellikle bunu bir gmp-map öğesi oluşturarak ve tarayıcının belge nesne modelinde (DOM) bu öğeye referans alarak yaparız. Bunu yapmak için div öğesini de kullanabilirsiniz (daha fazla bilgi), ancak gmp-map öğesini kullanmanız önerilir.

Aşağıdaki kod, gmp-map öğesini tanımlar ve center, zoom ve map-id parametrelerini ayarlar.

<gmp-map center="-25.344,131.031" zoom="4" map-id="DEMO_MAP_ID">
</gmp-map>

center ve zoom seçenekleri her zaman zorunludur. Yukarıdaki kodda, center özelliği API'ye haritanın nerede ortalanacağını söyler ve zoom özelliği haritanın yakınlaştırma düzeyini belirtir. Yakınlaştırma: 0 en düşük yakınlaştırma düzeyidir ve tüm Dünya'yı gösterir. Daha yüksek çözünürlüklerde Dünya'yı yakınlaştırmak için yakınlaştırma değerini daha yüksek ayarlayın.

Yakınlaştırma seviyeleri

Dünyanın tamamının tek bir resim olarak haritasını sunmak için ya çok büyük bir harita ya da çok düşük çözünürlüklü küçük bir harita gerekir. Bu nedenle, Google Haritalar ve Maps JavaScript API'deki harita resimleri, harita "döşemeleri" ve "yakınlaştırma düzeyleri" olarak ayrılır. Düşük yakınlaştırma seviyelerinde, küçük bir harita döşemesi grubu geniş bir alanı kapsar. Daha yüksek yakınlaştırma seviyelerinde ise döşemeler daha yüksek çözünürlüklüdür ve daha küçük bir alanı kapsar. 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: Kara parçası veya kıta
10: Şehir
15: Sokaklar
20: Binalar

Aşağıdaki üç resimde, Tokyo'nun aynı konumu 0, 7 ve 18 yakınlaştırma düzeylerinde gösterilmektedir.

Aşağıdaki kodda, gmp-map öğesinin boyutunu ayarlayan CSS açıklanmaktadır.

/* Set the size of the gmp-map element that contains the map */
gmp-map {
    height: 400px; /* The height is 400 pixels */
    width: 100%; /* The width is the width of the web page */
}

Yukarıdaki kodda, style öğesi gmp-map boyutunu ayarlar. Haritanın görünür olması için genişlik ve yüksekliği 0 pikselden büyük olacak şekilde ayarlayın. Bu durumda gmp-map web sayfasının genişliği boyunca görüntülenmek üzere 400 piksel yüksekliğe ve% 100 genişliğe ayarlanır. Yükseklik ve genişlik stillerinin her zaman açıkça ayarlanması önerilir.

Kontrol yuvası

Haritanıza HTML form kontrolleri eklemek için kontrol yuvasını kullanabilirsiniz. Yuva, haritada önceden tanımlanmış bir konumdur. Bir öğe için gereken konumu ayarlamak üzere slot özelliğini kullanın ve öğeleri gmp-map öğesinin içine yerleştirin. Aşağıdaki snippet'te, haritanın sol üst köşesine HTML etiketi ekleme işlemi gösterilmektedir.

<!-- The map, centered at Uluru, Australia. -->
<gmp-map center="-25.344,131.031" zoom="4" map-id="DEMO_MAP_ID">
  <div id="controls" slot="control-inline-start-block-start">
    <h3>My Google Maps Demo</h3>
  </div>
</gmp-map>

3. adım: JavaScript kodu ekleyin

Bu bölüm, Haritalar JavaScript API'sini bir web sayfasına nasıl yükleyeceğinizi ve API'yi kullanarak üzerine işaretleyici ekleyebileceğiniz kendi JavaScript'inizi nasıl yazacağınızı gösterir.

TypeScript

async function initMap(): Promise<void> {
  //  Request the needed libraries.
  const [{ Map }, { AdvancedMarkerElement }] = await Promise.all([
    google.maps.importLibrary("maps") as Promise<google.maps.MapsLibrary>,
    google.maps.importLibrary("marker") as Promise<google.maps.MarkerLibrary>,
  ]);
  // Get the gmp-map element.
  const mapElement = document.querySelector(
    "gmp-map"
  ) as google.maps.MapElement;

  // Get the inner map.
  const innerMap = mapElement.innerMap;

  // Set map options.
  innerMap.setOptions({
    mapTypeControl: false,
  });

  // Add a marker positioned at the map center (Uluru).
  const marker = new AdvancedMarkerElement({
    map: innerMap,
    position: mapElement.center,
    title: "Uluru/Ayers Rock",
  });
}
initMap();index.ts

JavaScript

async function initMap() {
    //  Request the needed libraries.
    const [{ Map }, { AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary("maps"),
        google.maps.importLibrary("marker"),
    ]);
    // Get the gmp-map element.
    const mapElement = document.querySelector("gmp-map");
    // Get the inner map.
    const innerMap = mapElement.innerMap;
    // Set map options.
    innerMap.setOptions({
        mapTypeControl: false,
    });
    // Add a marker positioned at the map center (Uluru).
    const marker = new AdvancedMarkerElement({
        map: innerMap,
        position: mapElement.center,
        title: "Uluru/Ayers Rock",
    });
}
initMap();index.js

Yukarıdaki kod, initMap() çağrıldığında aşağıdaki işlemleri yapar:

maps ve marker kitaplıklarını yükler.
Harita öğesini DOM'dan alır.
İç haritada ek harita seçenekleri ayarlar.
Haritaya işaretçi ekler.

Harita nesnesini alma ve seçenekleri ayarlama

innerMap, Map sınıfının bir örneğini temsil eder. Harita seçeneklerini ayarlamak için harita öğesinden innerMap örneğini alın ve setOptions işlevini çağırın. Aşağıdaki snippet'te, innerMap örneğinin DOM'dan nasıl alındığı ve ardından setOptions işlevinin nasıl çağrıldığı gösterilmektedir:

// Get the gmp-map element.
const mapElement = document.querySelector(
  "gmp-map"
) as google.maps.MapElement;

// Get the inner map.
const innerMap = mapElement.innerMap;

// Set map options.
innerMap.setOptions({
  mapTypeControl: false,
});

Haritanın yüklenmesini bekleyin.

gmp-map öğesi kullanılırken harita eşzamansız olarak yüklenir. Bu durum, başlatma sırasında başka istekler gönderilirse (ör. coğrafi konum veya yer ayrıntıları isteği) yarışma koşuluna neden olabilir. Kodunuzun yalnızca harita tamamen yüklendikten sonra çalışmasını sağlamak için başlatma işlevinizde addListenerOnce idle etkinlik işleyicisini kullanın.

// Do things once the map has loaded.
google.maps.event.addListenerOnce(innerMap, 'idle', () => {
    // Run this code only after the map has loaded.
    console.log("The map is now ready!");
});

Bu işlem, kodunuzun yalnızca harita yüklendikten sonra çalıştırılmasını sağlar. İşleyici, uygulamanın yaşam döngüsü boyunca yalnızca bir kez tetiklenir.

Eksiksiz örnek kod

Tam örnek kodu burada görebilirsiniz:

TypeScript

async function initMap(): Promise<void> {
  //  Request the needed libraries.
  const [{ Map }, { AdvancedMarkerElement }] = await Promise.all([
    google.maps.importLibrary("maps") as Promise<google.maps.MapsLibrary>,
    google.maps.importLibrary("marker") as Promise<google.maps.MarkerLibrary>,
  ]);
  // Get the gmp-map element.
  const mapElement = document.querySelector(
    "gmp-map"
  ) as google.maps.MapElement;

  // Get the inner map.
  const innerMap = mapElement.innerMap;

  // Set map options.
  innerMap.setOptions({
    mapTypeControl: false,
  });

  // Add a marker positioned at the map center (Uluru).
  const marker = new AdvancedMarkerElement({
    map: innerMap,
    position: mapElement.center,
    title: "Uluru/Ayers Rock",
  });
}
initMap();index.ts

JavaScript

async function initMap() {
    //  Request the needed libraries.
    const [{ Map }, { AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary("maps"),
        google.maps.importLibrary("marker"),
    ]);
    // Get the gmp-map element.
    const mapElement = document.querySelector("gmp-map");
    // Get the inner map.
    const innerMap = mapElement.innerMap;
    // Set map options.
    innerMap.setOptions({
        mapTypeControl: false,
    });
    // Add a marker positioned at the map center (Uluru).
    const marker = new AdvancedMarkerElement({
        map: innerMap,
        position: mapElement.center,
        title: "Uluru/Ayers Rock",
    });
}
initMap();index.js

CSS

/*
 * Always set the map height explicitly to define the size of the div element
 * that contains the map.
 */
gmp-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>Add a Map</title>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
    <!-- 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: "AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8", v: "weekly"});</script>
  </head>
  <body>
    <!-- The map, centered at Uluru, Australia. -->
    <gmp-map center="-25.344,131.031" zoom="4" map-id="DEMO_MAP_ID">
      <div id="controls" slot="control-inline-start-block-start">
        <h3>My Google Maps Demo</h3>
      </div>
    </gmp-map>
  </body>
</html>index.html

Örneği deneyin

JSFiddle.net

İşaretçiler hakkında daha fazla bilgi edinin:

İpuçları ve sorun giderme

Enlem/boylam koordinatlarını alma veya adresi coğrafi koordinatlara dönüştürme hakkında daha fazla bilgi edinin.
Haritayı özelleştirmek için stil ve özellik gibi seçenekleri değiştirebilirsiniz. Haritaları özelleştirme hakkında daha fazla bilgi için stil ve harita üzerinde çizim yapma kılavuzlarını inceleyin.
Kodunuzu test edip çalıştırmak, hata raporlarını okumak ve kodunuzla ilgili sorunları çözmek için web tarayıcınızdaki Geliştirici Araçları Konsolu'nu kullanın.
Chrome'da konsolu açmak için aşağıdaki klavye kısayollarını kullanın:
Command+Option+J (Mac'te) veya Control+Shift+J (Windows'da).
Google Haritalar'da bir konumun enlem ve boylam koordinatlarını almak için aşağıdaki adımları uygulayın.
1. Google Haritalar'ı bir tarayıcıda açın.
2. Koordinatlarını istediğiniz konumu haritada sağ tıklayın.
3. Görüntülenen içerik menüsünden Burada ne var? seçeneğini belirleyin. Haritanın ekranının alt kısmında bir kart görüntülenir. Enlem ve boylam koordinatlarını kartın son satırında bulabilirsiniz.
Bir adresi enlem ve boylam koordinatlarına Geocoding servisini kullanarak dönüştürebilirsiniz. Geliştirici kılavuzlarında Coğrafi Kodlama Hizmeti'ni kullanmaya başlama hakkında ayrıntılı bilgi verilmektedir.

JavaScript kullanarak işaretçi içeren bir Google Haritası ekleme Koleksiyonlar ile düzeninizi koruyun İçeriği tercihlerinize göre kaydedin ve kategorilere ayırın.

Giriş

Başlarken

1. adım: API anahtarı alın

2. adım: HTML sayfası oluşturun

Kodu anlama

Uygulamanızı HTML5 olarak beyan etme

Maps JavaScript API'yi yükleme

gmp-map öğesi oluşturma

Yakınlaştırma seviyeleri

Kontrol yuvası

3. adım: JavaScript kodu ekleyin

TypeScript

JavaScript

Harita nesnesini alma ve seçenekleri ayarlama

Haritanın yüklenmesini bekleyin.

Eksiksiz örnek kod

TypeScript

JavaScript

CSS

HTML

Örneği deneyin

İşaretçiler hakkında daha fazla bilgi edinin:

İpuçları ve sorun giderme

JavaScript kullanarak işaretçi içeren bir Google Haritası ekleme

`gmp-map` öğesi oluşturma