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 da bilgi verir.

Aşağıda, bu eğitimle 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ı yapacağı 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.
Faturalandırmayı etkinleştirin. Daha fazla bilgi için Kullanım ve Faturalandırma başlıklı makaleyi inceleyin.

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 komut dosyası 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

Örnekteki bu aşamada:

!DOCTYPE html bildirimiyle uygulamayı HTML5 olarak bildirdiyseniz.
Maps JavaScript API'yi bootstrap yükleyiciyi kullanarak yüklediyseniz.
Haritayı tutacak bir gmp-map öğesi oluşturdu.

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>

Mevcut tarayıcıların çoğu, bu DOCTYPE ile "standartlar modunda" tanımlanan içeriği oluşturur. Bu da uygulamanızın tarayıcılar arası uyumluluğunun daha yüksek 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.

Uygunluk modunda çalışan bazı CSS'lerin standartlar modunda geçerli olmadığını unutmayın. Daha net bir ifadeyle, yüzde tabanlı tüm boyutlar üst blok öğelerden devralınmalıdır. Bu öğelerden herhangi biri boyut belirtemezse 0 x 0 piksel boyutunda olduğu 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

Bootstrap yükleyici, Maps JavaScript API'yi 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ı alma 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şturup 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 parçaları grubu geniş bir alanı kapsar. Daha yüksek yakınlaştırma seviyelerinde ise parçalar 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 0, 7 ve 18 yakınlaştırma düzeylerindeki aynı konumu 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 öğesinin 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 örnekte, gmp-map, web sayfasının genişliği boyunca gösterilmesi için 400 piksel yüksekliğe ve% 100 genişliğe ayarlanmıştır. Yükseklik ve genişlik stillerinin her zaman açıkça ayarlanması önerilir.

Kontrollü yerleştirme

Haritanıza HTML formu kontrolleri eklemek için kontrol yerleştirme özelliğini 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ümde, Maps JavaScript API'nin bir web sayfasına nasıl yükleneceği ve API'yi kullanarak işaretçi içeren bir harita eklemek için kendi JavaScript'inizi nasıl yazacağınız gösterilmektedir.

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 addListenerOnceidle 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 ile ilgili kılavuzları 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. Haritada koordinatlarını istediğiniz tam konumu sağ tıklayın.
3. Görüntülenen içerik menüsünden Burada ne var? seçeneğini belirleyin. Haritada ekranın alt kısmında bir kart gösterilir. Enlem ve boylam koordinatlarını kartın son satırında bulabilirsiniz.
Coğrafi kodlama hizmetini kullanarak bir adresi enlem ve boylam koordinatlarına 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

Kontrollü yerleştirme

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