Maps JavaScript API Uygulamanızı V2'den V3'e Yükseltme

Koleksiyonlar ile düzeninizi koruyun İçeriği tercihlerinize göre kaydedin ve kategorilere ayırın.

Maps JavaScript API v2, 26 Mayıs 2021'den itibaren kullanımdan kaldırılacaktır. Sonuç olarak, sitenizin v2 sürümü haritaları çalışmayı durduracak ve JavaScript hataları döndürecektir. Sitenizde haritaları kullanmaya devam etmek için Maps JavaScript API v3'e geçin. Bu kılavuz, bu süreçte size yardımcı olacaktır.

Genel bakış

Her uygulamanın taşıma işlemi biraz daha farklı olacaktır; ancak bazı projelerde sık kullanılan bazı adımlar vardır:

  1. Yeni anahtar alın. Maps JavaScript API, artık anahtarları yönetmek için Google Cloud Console'u kullanıyor. Hâlâ v2 anahtarı kullanıyorsanız taşıma işleminize başlamadan önce yeni API anahtarınızı aldığınızdan emin olun.
  2. API Önyüklemenizi güncelleyin. Çoğu uygulama, Maps JavaScript API v3'ü şu kodla yükler:
    <script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>
    
  3. Kodunuzu güncelleyin. Gerekli değişiklik miktarı uygulamanıza büyük ölçüde bağlıdır. Yaygın değişiklikler şunlardır:
    • Her zaman google.maps ad alanına başvurun. Sürüm 3'te tüm Maps JavaScript API kodu, genel ad alanı yerine google.maps.* ad alanında depolanır. Çoğu nesne de bu sürecin bir parçası olarak yeniden adlandırıldı. Örneğin, artık GMap2 yerine google.maps.Map yükleyeceksiniz.
    • Eski yöntemlere yapılan tüm referansları kaldırın. GDownloadURL ve GLog gibi genel amaçlı yardımcı program yöntemleri kaldırıldı. Bu işlevi üçüncü taraf yardımcı program kitaplıklarıyla değiştirin veya bu referansları kodunuzdan kaldırın.
    • (İsteğe bağlı) Kodunuza kitaplık ekleyin. Çoğu özellik, yardımcı program kitaplıklarına harici hale getirilmiştir. Böylece her uygulamanın, yalnızca kullanılacak API parçalarını yüklemesi gerekir.
    • (İsteğe bağlı) Projenizi, v3 istisnalarını kullanacak şekilde yapılandırın. v3 bitleri, kodunuzu Closure Compiler ile doğrulamaya yardımcı olmak veya IDE'nizde otomatik tamamlamayı tetiklemek için kullanılabilir. Gelişmiş Derleme ve Kapsamlar hakkında daha fazla bilgi edinin.
  4. Test edin ve tekrarlayın. Bu noktada yapmanız gereken bazı işler var. Ancak yeni v3 haritalar uygulamanıza doğru ilerlemeye hazır olduğunuzu belirtmek isteriz.

Maps JavaScript API'nin V3'teki değişiklikler

Taşıma işleminizi planlamadan önce Maps JavaScript API v2 ve Maps JavaScript API v3 arasındaki farkları anlamanız gerekir. Maps JavaScript API'nin en yeni sürümü; sıfırdan, modern JavaScript programlama tekniklerine, kitaplık kullanımında artışa ve basitleştirilmiş bir API'ye odaklanarak baştan sona yazılmıştır. API'ye birçok yeni özellik eklendi ve birçok tanıdık özellik değiştirildi, hatta kaldırıldı. Bu bölümde, iki sürüm arasındaki temel farklılıklardan bazıları vurgulanmaktadır.

v3 API'deki değişikliklerden bazıları şunlardır:

  • Modern bir temel kitaplık. Ek işlevlerin çoğu, kitaplıklara taşındı. Core API'nin yükleme ve ayrıştırma sürelerini azaltmaya yardımcı olarak haritanızın tüm cihazlarda hızlı bir şekilde yüklenmesini sağlar.
  • Poligon oluşturma ve işaretçi yerleşimi gibi çeşitli özelliklerin performansı iyileştirildi.
  • Mobil proxy'ler ve kurumsal güvenlik duvarları tarafından kullanılan paylaşılan adreslere daha iyi uyum sağlamak için istemci tarafı kullanım sınırlarına yeni bir yaklaşım.
  • Modern tarayıcılar ve mobil tarayıcılar için destek eklendi. Internet Explorer 6 desteği kaldırıldı.
  • Genel amaçlı yardımcı sınıfların birçoğu (GLog veya GDownloadUrl) kaldırıldı. Günümüzde Kloş veya jQuery gibi benzer işlevler sağlayan birçok mükemmel JavaScript kitaplığı mevcuttur.
  • Herhangi bir mobil cihaza yüklenecek bir HTML5 Street View uygulaması.
  • Kayak pistlerinin, kiralık evlerin veya diğer ilgi çekici yerlerin panoramalarını paylaşmanızı sağlayan, kendi fotoğraflarınızın olduğu Özel Street View panoramaları.
  • Temel haritadaki öğelerin görünümünü benzersiz görsel stilinize uyacak şekilde değiştirmenize olanak tanıyan Stilli Haritalar özelleştirmeleri.
  • ElevationService ve Mesafe Matrisi gibi yeni hizmetler için destek.
  • İyileştirilmiş yol tarifi hizmetleri; alternatif rotalar, rota optimizasyonu (seyahat eden satıcı problemine benzer çözümler), bisikletli yol tarifleri (bisiklet bisikleti katmanıyla), toplu taşımayla yol tarifleri ve sürüklenebilir yol tarifleri sunar.
  • Geocoding API v2'deki accuracy değerinden daha doğru tür bilgilerini sağlayan güncellenmiş bir Geocoding biçimi.
  • Tek bir Harita üzerinde birden fazla Bilgi Penceresi desteği

Uygulamanızı Yeni Sürüme Geçirme

Yeni Anahtarınız

Maps JavaScript API v3, v2'den yeni bir anahtar sistemi kullanır. Uygulamanızla zaten bir v3 anahtarı kullanıyor olabilirsiniz. Bu durumda herhangi bir değişiklik yapmanız gerekmez. Doğrulamak için key parametresi için Maps JavaScript API'yi yüklediğiniz URL'yi kontrol edin. Anahtar değeri 'ABQIAA' ile başlıyorsa bir v2 anahtarı kullanıyorsunuz demektir. v2 anahtarınız varsa taşıma işleminin parçası olarak v3 anahtarına yükseltme yapmanız gerekir. Bu anahtarlar:

Maps JavaScript API v3 yüklenirken anahtar aktarılır. API anahtarları oluşturma hakkında daha fazla bilgi edinin.

Google Maps API for Work müşterisiyseniz key parametresini kullanmak yerine client parametresiyle bir istemci kimliği kullanıyor olabileceğinizi unutmayın. İstemci kimlikleri Maps JavaScript API v3'te desteklenmeye devam eder ve önemli yükseltme sürecinden geçmesi gerekmez.

API yükleniyor

Kodunuzda yapmanız gereken ilk değişiklik, API'yi nasıl yükleyeceğinizdir. Sürüm 2'de, Maps JavaScript API'yi http://maps.google.com/maps adresine gönderilen bir istek üzerinden yüklersiniz. Maps JavaScript API v3 sürümünü yüklüyorsanız aşağıdaki değişiklikleri yapmanız gerekir:

  1. //maps.googleapis.com/maps/api/js API'sini yükleyin
  2. file parametresini kaldırın.
  3. key parametresini yeni v3 anahtarınızla güncelleyin. Google Maps API for Work müşterileri client parametresi kullanmalıdır.
  4. (Yalnızca Google Haritalar Platformu Premium Planı) client parametresinin, Google Haritalar Platformu Premium Planı Geliştirici Kılavuzu'nda açıklandığı gibi sağlandığından emin olun.
  5. Yayınlanan en son sürümü istemek veya değeri, v3 sürüm oluşturma şemasına göre değiştirmek için v parametresini kaldırın.
  6. (İsteğe bağlı) hl parametresini language ile değiştirin ve değerini koruyun.
  7. (İsteğe bağlı) İsteğe bağlı kitaplıkları yüklemek için libraries parametresi ekleyin.

En basit örnekte, v3 bootstrap'i yalnızca API anahtarı parametrenizi belirtir:

<script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>

Aşağıdaki örnekte, Almanca dilinde JavaScript JavaScript API v2'nin son sürümü gösterilmektedir:

<script src="//maps.google.com/maps?file=api&v=2.x&key=YOUR_API_KEY&hl=de"></script>

Aşağıdaki örnek v3 için eşdeğer bir istektir.

<script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&language=de"></script>

google.maps ad alanı tanıtımı

Maps JavaScript API v3'teki en dikkat çekici değişiklik, google.maps ad alanının kullanıma sunulmasıdır. v2 API, tüm nesneleri varsayılan olarak Küresel ad alanına yerleştirir ve bu da adlandırma çakışmalarına neden olabilir. v3'te, tüm nesneler google.maps ad alanının içinde bulunur.

Uygulamanızı v3'e taşırken, yeni ad alanından yararlanmak için kodunuzu değiştirmeniz gerekir. Ne yazık ki &gt.&qt; araması yapmak ve "google.maps." ile değiştirmek tamamen işe yaramaz, ancak kodunuzu gözden geçirirken geçerli bir temel kural izlemek önemlidir. Aşağıda, v2 ve v3'de eş değer sınıflara ilişkin bazı örnekler verilmiştir.

v2 v3
GMap2 google.maps.Map
GLatLng google.maps.LatLng
GInfoWindow google.maps.InfoWindow
GMapOptions google.map.MapOptions
G_API_VERSION google.maps.version
GPolyStyleOptions google.maps.PolygonOptions
or google.maps.PolylineOptions

Eski Kodu Kaldırma

Maps JavaScript API v3, v2'deki işlevlerin çoğu için paraleller olsa da, artık desteklenmeyen bazı sınıflar mevcuttur. Taşıma işlemi kapsamında bu sınıfları üçüncü taraf yardımcı program kitaplıklarıyla değiştirmeli veya bu referansları kodunuzdan kaldırmalısınız. Closure veya jQuery gibi benzer işlevler sağlayan çok sayıda mükemmel JavaScript kitaplığı mevcuttur.

Aşağıdaki sınıflar için Maps JavaScript API v3'te paralellik yoktur:

GBoundsGLanguage
GBrowserIsCompatibleGLayer
GControlGLog
GControlAnchorGMercatorProjection
GControlImplGNavLabelControl
GControlPositionGObliqueMercator
GCopyrightGOverlay
GCopyrightCollectionGPhotoSpec
GDownloadUrlGPolyEditingOptions
GDraggableObjectGScreenOverlay
GDraggableObjectOptionsGStreetviewFeatures
GFactualGeocodeCacheGStreetviewLocation
GGeoAddressAccuracyGStreetviewOverlay
GGeocodeCacheGStreetviewUserPhotosOptions
GGoogleBarGTileLayerOptions
GGoogleBarAdsOptionsGTileLayerOverlayOptions
GGoogleBarLinkTargetGTrafficOverlayOptions
GGoogleBarListingTypesGUnload
GGoogleBarOptionsGXml
GGoogleBarResultListGXmlHttp
GInfoWindowTabGXslt
GKeyboardHandler

Kodu Karşılaştırma

v2 ve v3 API'ler ile yazılmış iki basit ama basit uygulamayı karşılaştıralım.

<!DOCTYPE html>
<html>
  <head>
    <script src="//maps.google.com/maps?file=api&v=2&key=YOUR_API_KEY"></script>
    <style>
      html, body, #map { height: 100%; margin: 0; }
    </style>
    <script>
    function initialize() {
      if (GBrowserIsCompatible()) {
        var map = new GMap2(
            document.getElementById('map'));
        map.setCenter(new GLatLng(37.4419, -122.1419), 13);
        map.setUIToDefault();

        map.addOverlay(new GMarker(new GLatLng(37.4419, -122.1419)));

      }
    }
    </script>
  </head>
  <body onload="initialize()" onunload="GUnload()">
    <div id="map"></div>
  </body>
</html>
    
<!DOCTYPE html>
<html>
  <head>
    <script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>
    <style>
      html, body, #map { height: 100%; margin: 0; }
    </style>
    <script>
    function initialize() {
      var map = new google.maps.Map(
        document.getElementById('map'), {
          center: new google.maps.LatLng(37.4419, -122.1419),
          zoom: 13,
          mapTypeId: google.maps.MapTypeId.ROADMAP
      });

      var marker = new google.maps.Marker({
            position: new google.maps.LatLng(37.4419, -122.1419),
            map: map
      });

    }
    google.maps.event.addDomListener(window, 'load', initialize);
    </script>
  </head>
  <body>
    <div id="map"></div>
  </body>
</html>
    

Gördüğünüz gibi iki uygulama arasında birkaç fark vardır. Önemli değişiklikler şunlardır:

  • API'nin yüklendiği adres değişti.
  • GBrowserIsCompatible() ve GUnload() yöntemleri artık v3'te gerekli değildir ve API'den kaldırılmıştır.
  • GMap2 nesnesi, API'deki ana nesne olarak google.maps.Map ile değiştirilir.
  • Özellikler artık Seçenekler sınıfları üzerinden yükleniyor. Yukarıdaki örnekte, satır içi MapOptions nesnesi aracılığıyla bir harita yüklemek için gereken üç özelliği (center, zoom ve mapTypeId) ayarlıyoruz.
  • Varsayılan kullanıcı arayüzü v3'te varsayılan olarak etkindir. MapOptions nesnesinde disableDefaultUI özelliğini doğru olarak ayarlayarak bunu devre dışı bırakabilirsiniz.

Özet

Bu noktada, Maps JavaScript API'nin v2'den v3'e geçişinizde yer alan bazı önemli noktalar hakkında bilgi sahibi oldunuz. Bilmeniz gereken daha fazla bilgi var ancak bunlar uygulamanıza bağlı olarak değişebilir. Aşağıdaki bölümlerde, karşılaşabileceğiniz belirli durumlar için taşıma talimatları verilmiştir. Ek olarak, yeni sürüme geçme işlemi sırasında işinize yarayabilecek çeşitli kaynaklar vardır.

  • Maps JavaScript API v3 Geliştirici Belgeleri, API ve API'nin işleyiş şekli hakkında daha fazla bilgi edinmek için en iyi yerdir.
  • Maps JavaScript API v3 Başvurusu, v3 API'deki yeni sınıflar ve yöntemler hakkında daha fazla bilgi edinmenize yardımcı olacak.
  • Stack Overflow topluluğu, kodlarla ilgili sorularınızı sorabileceğiniz mükemmel bir yerdir. Sitede, Maps JavaScript API ile ilgili soru ve cevaplar için ##39;google-maps' veya 'google-maps-api-3' etiketleri kullanılır.
  • Google Haritalar Platformu Premium Planı müşterileri, Google Haritalar Platformu Premium Planı Dokümanlarını okumak isteyecektir.
  • Google Geo Developers Blogu, API'de yapılan en son değişiklikleri öğrenmenin harika bir yoludur.

Makaleyle ilgili sorularınız veya sorunlarınız varsa lütfen bu sayfanın üst kısmındaki GERİ BİLDİRİM GÖNDER bağlantısını kullanın.

Ayrıntılı Referans

Bu bölümde, Maps JavaScript API'nin v2 ve v3'e ait en popüler özelliklerin ayrıntılı bir karşılaştırması sunulmaktadır. Referansın her bölümü, ayrı ayrı okunacak şekilde tasarlanmıştır. Bu referansın tamamını okumamanızı öneririz. Taşıma işlemini duruma göre kolaylaştırmak için bu materyali kullanın.

  • Etkinlikler: Etkinlikleri kaydetme ve işleme.
  • Kontroller - harita üzerinde görünen gezinme denetimlerini manipüle eder.
  • Yer paylaşımları - haritada nesne ekleme ve düzenleme.
  • Harita Türleri - Temel haritayı oluşturan parçalar.
  • Katmanlar: KML veya Trafik katmanları gibi bir grup olarak içerik ekleme ve düzenleme.
  • Hizmetler: Google'ın coğrafi kodlama, yol tarifi veya Street View hizmetleri ile çalışır.

Etkinlikler

Maps JavaScript API v3'ün etkinlik modeli, v2'de kullanılan modele benzerdir ancak arka planda çok fazla değişiklik yapılmıştır.

Kontroller

Maps JavaScript API, kullanıcıların haritanızla etkileşim kurmasını sağlayan kullanıcı arayüzü kontrollerini gösterir. Bu denetimlerin görünümünü özelleştirmek için API'yi kullanabilirsiniz.

Bindirmeler

Bindirmeler; noktaları, çizgileri, alanları veya nesne koleksiyonlarını tanımlamak için haritaya eklediğiniz nesneleri yansıtır.

Harita Türleri

v2 ve v3'te bulunan harita türleri biraz farklı olsa da, tüm temel harita türleri API'nin her iki sürümünde de kullanılabilir. v2, varsayılan olarak standart "boyalı" yol haritası karolarını kullanır. Bununla birlikte, v3, google.maps.Map nesnesi oluşturulurken belirli bir harita türünün sağlanmasını gerektirir.

Katmanlar

Katmanlar, haritadaki bir veya daha fazla bindirmeden oluşan nesnelerdir. Tek bir birim olarak müdahale edilebilir ve genellikle nesne koleksiyonlarını yansıtır.

Hizmetler