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

MVC Desteği İçin Yeni Etkinlik

v3 API, MVC durum değişikliklerini yansıtmak için yeni bir etkinlik türü ekler. Artık iki tür etkinlik vardır:

• Kullanıcı etkinlikleri ("tıklama" fare etkinlikleri gibi), DOM'dan Haritalar JavaScript API'sine iletilir. Bu etkinlikler, standart DOM etkinliklerinden ayrı ve farklıdır.
• MVC durum değişikliği bildirimleri, Haritalar API nesnelerindeki değişiklikleri yansıtır ve property_changed kuralı kullanılarak adlandırılır.

Her Haritalar API nesnesi, bir dizi adlandırılmış etkinlik dışa aktarır. Belirli etkinliklerle ilgilenen uygulamalar, bu etkinlikler için etkinlik dinleyicileri kaydetmeli ve bu etkinlikler alındığında kodu çalıştırmalıdır. Bu etkinlik odaklı mekanizma, ad alanının GEvent yerine google.maps.event olarak değiştiği dışında hem Maps JavaScript API v2 hem de v3'te aynıdır:

GEvent.addListener(map, 'click', function() {
  alert('You clicked the map.');
});

google.maps.event.addListener(map, 'click', function() {
  alert('You clicked the map.');
});

Etkinlik işleyicileri kaldırma

Performans nedeniyle, artık gerekli olmayan bir etkinlik işleyiciyi kaldırmak en iyisidir. Bir etkinlik işleyiciyi kaldırma işlemi, v2 ve v3'te aynı şekilde çalışır:

1. Bir etkinlik işleyici oluşturduğunuzda opak bir nesne (v2'de GEventListener, v3'te MapsEventListener) döndürülür.
2. Etkinlik işleyiciyi kaldırmak istediğinizde bu nesneyi removeListener() yöntemine (v2'de GEvent.removeListener() veya v3'te google.maps.event.removeListener()) göndererek etkinlik işleyiciyi kaldırabilirsiniz.

DOM Etkinliklerini Dinleme

DOM (Belge Nesne Modeli) etkinliklerini yakalamak ve bunlara yanıt vermek istiyorsanız v3, v2'deki GEvent.addDomListener() yöntemine eşdeğer olan google.maps.event.addDomListener() statik yöntemini sağlar.

Etkinliklerde İletilen Bağımsız Değişkenleri Kullanma

Kullanıcı arayüzü etkinlikleri genellikle bir etkinlik bağımsız değişkeni ileterek etkinlik işleyicinin bu bağımsız değişkene erişmesini sağlar. v3'teki çoğu etkinlik bağımsız değişkeni, API'deki nesnelerle daha tutarlı olması için basitleştirildi. (Ayrıntılar için v3 Referansı'na bakın.)

v3 etkinlik işleyicilerinde overlay bağımsız değişkeni yoktur. v3 haritasında bir click etkinliği kaydederseniz geri çağırma yalnızca kullanıcı ana haritayı tıkladığında gerçekleşir. Tıklanabilir yer paylaşımlarına ek geri çağırma işlevleri kaydederek bu tıklamalara tepki verebilirsiniz.

// Passes an overlay argument when clicking on a map

var map = new GMap2(document.getElementById('map'));
map.setCenter(new GLatLng(-25.363882, 131.044922), 4);
map.setUIToDefault();

GEvent.addListener(map,'click', function(overlay, latlng) {
  if (latlng) {
    var marker = new GMarker(latlng);
    map.addOverlay(marker);
  }
});

// Passes only an event argument

var myOptions = {
    center: new google.maps.LatLng(-25.363882, 131.044922),
    zoom: 4,
    mapTypeId: google.maps.MapTypeId.ROADMAP
};

var map = new google.maps.Map(document.getElementById('map'),
    myOptions);

google.maps.event.addListener(map, 'click', function(event) {
  var marker = new google.maps.Marker({
      position: event.latLng,
      map: map
  });
});

Kontrol türlerinde yapılan değişiklikler

v3 API ile control türlerinde bazı değişiklikler yapıldı.

1. v3 API, arazi haritaları ve özel harita türleri ekleme özelliği de dahil olmak üzere ek harita türlerini destekler.
2. GHierarchicalMapTypeControl adlı v2 hiyerarşik kontrolü artık kullanılamıyor. google.maps.MapTypeControlStyle.HORIZONTAL_BAR denetimini kullanarak benzer bir etki elde edebilirsiniz.
3. GMapTypeControl tarafından 2. sürümde sağlanan yatay düzen, 3. sürümde kullanılamaz.

Haritaya kontrol ekleme

Maps JavaScript API v2 ile haritanıza, harita nesnenizin addControl() yöntemi aracılığıyla denetimler eklersiniz. 3. sürümde, denetimlere doğrudan erişmek veya denetimleri değiştirmek yerine, ilişkili MapOptions nesnesini değiştirirsiniz. Aşağıdaki örnekte, haritanın aşağıdaki denetimleri eklemek için nasıl özelleştirileceği gösterilmektedir:

• Kullanıcının mevcut harita türleri arasında geçiş yapmasına olanak tanıyan düğmeler
• harita ölçeği

var map = new GMap2(document.getElementById('map'));
map.setCenter(new GLatLng(-25.363882, 131.044922), 4);

// Add controls
map.addControl(new GMapTypeControl());
map.addControl(new GScaleControl());

var myOptions = {
    center: new google.maps.LatLng(-25.363882, 131.044922),
    zoom: 4,
    mapTypeId: google.maps.MapTypeId.ROADMAP,

    // Add controls
    mapTypeControl: true,
    scaleControl: true
};

var map = new google.maps.Map(document.getElementById('map'),
    myOptions);

Haritada Konum Kontrolleri

Konumlandırma kontrolleri, 3. sürümde büyük ölçüde değişti. addControl() yöntemi, 2. sürümde kontrol elemanının haritanın köşelerine göre konumunu belirtmenize olanak tanıyan isteğe bağlı ikinci bir parametre alır.

3. sürümde, bir kontrolün konumunu kontrol seçeneklerinin position mülkü aracılığıyla belirlersiniz. Bu denetimlerin konumlandırması mutlak değildir. Bunun yerine API, denetimleri belirli kısıtlamalar (harita boyutu gibi) dahilinde mevcut harita öğelerinin etrafında "akıtarak" akıllıca düzenler. Bu düzen, varsayılan kontrollerin kontrollerinizle uyumlu olmasını sağlar. Daha fazla bilgi için v3'te konumlandırmayı kontrol etme başlıklı makaleyi inceleyin.

Aşağıdaki kod, yukarıdaki örneklerdeki kontrolleri yeniden konumlandırır:

var map = new GMap2(document.getElementById('map'));
map.setCenter(new GLatLng(-25.363882, 131.044922), 4);

// Add map type control
map.addControl(new GMapTypeControl(), new GControlPosition(
    G_ANCHOR_TOP_LEFT, new GSize(10, 10)));

// Add scale
map.addControl(new GScaleControl(), new GControlPosition(
    G_ANCHOR_BOTTOM_RIGHT, new GSize(20, 20)));

var myOptions = {
  center: new google.maps.LatLng(-25.363882, 131.044922),
  zoom: 4,
  mapTypeId: google.maps.MapTypeId.ROADMAP,

  // Add map type control
  mapTypeControl: true,
  mapTypeControlOptions: {
      style: google.maps.MapTypeControlStyle.HORIZONTAL_BAR,
      position: google.maps.ControlPosition.TOP_LEFT
  },

  // Add scale
  scaleControl: true,
  scaleControlOptions: {
      position: google.maps.ControlPosition.BOTTOM_RIGHT
  }
};

var map = new google.maps.Map(document.getElementById('map'),
    myOptions);

Özel Denetimler

Özel gezinme kontrolleri oluşturmak için Maps JavaScript API'yi kullanın. Denetimleri v2 API ile özelleştirmek için GControl sınıfını alt sınıfa alır ve initialize() ile getDefaultPosition() yöntemleri için işleyiciler tanımlarsınız. GControl sınıfının v3'teki eşdeğeri yoktur. Bunun yerine denetimler DOM öğeleri olarak temsil edilir. v3 API ile özel bir denetim eklemek için bir Node öğesinin (ör. <div> öğesi) alt öğesi olarak bir oluşturucuda denetim için bir DOM yapısı oluşturun ve tüm DOM etkinliklerini işlemek üzere etkinlik dinleyicileri ekleyin. Haritanıza özel denetim örneği eklemek için Node öğesini haritaların controls[position] dizisine gönderin.

Yukarıda belirtilen arayüz koşullarına uyan bir HomeControl sınıfı uygulaması verildiğinde (ayrıntılar için Özel Kontroller dokümanlarına bakın), aşağıdaki kod örnekleri bir haritaya özel kontrol eklemeyi gösterir.

map.addControl(new HomeControl(),
    GControlPosition(G_ANCHOR_TOP_RIGHT, new GSize(10, 10)));

var homeControlDiv = document.createElement('DIV');
var homeControl = new HomeControl(homeControlDiv, map);

map.controls[google.maps.ControlPosition.TOP_RIGHT].push(
    homeControlDiv);

Yer paylaşımları ekleme ve kaldırma

Yer paylaşımı tarafından temsil edilen nesne türleri, v2 ile v3 arasında aynıdır ancak farklı şekilde ele alınır.

v2 API'deki yer paylaşımları, GMap2 nesnesinin addOverlay() ve removeOverlay() yöntemleri kullanılarak haritaya eklenip haritadan kaldırılıyordu. 3. sürümde, ilişkili yer paylaşımı seçenekleri sınıfının map mülkünü kullanarak bir haritayı yer paylaşımına atarsınız. Ayrıca, yer paylaşımı nesnesinin setMap() yöntemini çağırarak ve istediğiniz haritayı belirterek doğrudan yer paylaşımı ekleyebilir veya kaldırabilirsiniz. Yer paylaşımını kaldırmak için harita özelliğini null olarak ayarlayın.

clearOverlays() yöntemi v3'te mevcut değildir. Bir dizi yer paylaşımını yönetmek istiyorsanız yer paylaşımlarını barındıracak bir dizi oluşturmanız gerekir. Bu diziyi kullanarak, dizideki her yer paylaşımı için setMap() işlevini çağırabilirsiniz (kaldırmanız gerekiyorsa null parametresini iletin).

Sürüklenebilir İşaretçiler

İşaretçileri varsayılan olarak tıklayabilirsiniz ancak sürükleyemezsiniz. Aşağıdaki iki örnekte sürüklenebilir bir işaretçi eklenmiştir:

var myLatLng = new GLatLng(-25.363882, 131.044922);
var map = new GMap2(document.getElementById('map'));
map.setCenter(myLatLng, 4);

var marker = new GMarker(latLng, {
  draggable: true
});
map.addOverlay(marker);

var myLatLng = new google.maps.LatLng(-25.363882, 131.044922);
var map = new google.maps.Map(
  document.getElementById('map'), {
  center: myLatLng,
  zoom: 4,
  mapTypeId: google.maps.MapTypeId.ROADMAP
});

var marker = new google.maps.Marker({
    position: myLatLng,
    draggable: true,
    map: map
});

Simgeler

Varsayılan işaretçi yerine gösterilecek özel bir simge tanımlayabilirsiniz. v2'de özel bir resim kullanmak için G_DEFAULT_ICON type'dan bir GIcon örneği oluşturabilir ve bunu değiştirebilirsiniz. Resminiz varsayılan simgeden daha büyük veya daha küçükse bunu bir GSize örneğiyle belirtmeniz gerekir. v3 API bu süreci biraz basitleştirir. İşaretçinin icon mülkünü özel resminizin URL'sine ayarladığınızda API, simgeyi otomatik olarak boyutlandırır.

Maps JavaScript API, karmaşık simgeler için de destek sağlar. Karmaşık simgeler birden fazla karo, karmaşık şekiller içerebilir veya resimlerin diğer yer paylaşımlarına göre nasıl gösterileceğinin "yığın sırasını" belirtebilir. v2'de bir işaretçiye şekil eklemek için her GIcon örneğinde ek mülkü belirtmeniz ve bunu bir GMarker oluşturucusuna seçenek olarak iletmeniz gerekir. 3. sürümde, bu şekilde belirtilen simgelerin icon özelliklerinin Icon türüne ayarlanması gerekir. İşaretçi gölgeleri v3'te desteklenmez.

Aşağıdaki örneklerde, Avustralya'daki Bondi Plajı'nda bir plaj bayrağı gösterilmektedir. Simgenin şeffaf kısmı tıklanamaz:

var map = new GMap2(document.getElementById('map'));
map.setCenter(new GLatLng(-25.363882, 131.044922), 4);
map.setUIToDefault();

var flagIcon = new GIcon(G_DEFAULT_ICON);
flagIcon.image = '/images/beachflag.png';
flagIcon.imageMap = [1, 1, 1, 20, 18, 20, 18 , 1];
var bbLatLng = new GLatLng(-33.890542, 151.274856);

map.addOverlay(new GMarker(bbLatLng, {
  icon: flagIcon
}));

var map = new google.maps.Map(
  document.getElementById('map'), {
  center: new google.maps.LatLng(-25.363882, 131.044922),
  zoom: 4,
  mapTypeId: google.maps.MapTypeId.ROADMAP
});

var shape = {
    coord: [1, 1, 1, 20, 18, 20, 18 , 1],
    type: 'poly'
};
var bbLatLng = new google.maps.LatLng(-33.890542, 151.274856);

var bbMarker = new google.maps.Marker({
    icon: '/images/beachflag.png'
    shape: shape,
    position: bbLatLng,
    map: map
});

Çoklu çizgiler

Bir çok çizgi, bir LatLng dizisi ve bu konumları sıralı bir sırada birbirine bağlayan bir dizi çizgi segmentinden oluşur. Polyline nesnesi oluşturma ve görüntüleme işlemi, v3'te GPolyline nesnesi kullanma işlemine benzer. Aşağıdaki örneklerde, Zürih'ten Singapur üzerinden Sydney'e giden yarı şeffaf, 3 piksel genişliğinde bir jeodezik poli çizgisi çizilmiştir:

var polyline = new GPolyline(
  [
    new GLatLng(47.3690239, 8.5380326),
    new GLatLng(1.352083, 103.819836),
    new GLatLng(-33.867139, 151.207114)
  ],
  '#FF0000', 3, 0.5, {
  geodesic: true
});

map.addOverlay(polyline);

var polyline = new google.maps.Polyline({
  path: [
    new google.maps.LatLng(47.3690239, 8.5380326),
    new google.maps.LatLng(1.352083, 103.819836),
    new google.maps.LatLng(-33.867139, 151.207114)
  ],
  strokeColor: '#FF0000',
  strokeOpacity: 0.5,
  strokeWeight: 3,
  geodesic: true
});

polyline.setMap(map);

Kodlanmış çoklu çizgiler

Polyline nesnelerini doğrudan kodlanmış poli çizgilerden oluşturmak için v3'te destek yoktur. Bunun yerine, Geometri Kitaplığı, poli çizgileri kodlama ve kodlarını çözme yöntemleri sağlar. Bu kitaplığın nasıl yükleneceği hakkında daha fazla bilgi için v3 Haritalar API'sindeki Kitaplıklar bölümüne bakın.

Aşağıdaki örneklerde aynı kodlanmış çoklu çizgi çizilmektedir. v3 kodunda, google.maps.geometry.encoding ad alanındaki decodePath() yöntemi kullanılmaktadır.

var polyline = new GPolyline.fromEncoded({
  points: 'kwb`Huqbs@ztzwGgvpdQbw}uEoif`H',
  levels: 'PPP',
  zoomFactor: 2,
  numLevels: 18,
  color: '#ff0000',
  opacity: 0.8,
  weight: 3
});

map.addOverlay(polyline);

var polyline = new google.maps.Polyline({
  path: google.maps.geometry.encoding.decodePath(
    'kwb`Huqbs@ztzwGgvpdQbw}uEoif`H'),
  strokeColor: '#FF0000',
  strokeOpacity: 0.5,
  strokeWeight: 3,
});

polyline.setMap(map);

Poligonlar

Poligon, kapalı bir döngü içindeki bir bölgeyi tanımlar. Polyline nesnesine benzer şekilde, Polygon nesneleri de sıralı bir sıradaki bir dizi noktadan oluşur. v3 Polygon sınıfı, v2 GPolygon sınıfıyla hemen hemen aynıdır. Tek fark, döngüyü kapatmak için artık yolun sonunda başlangıç köşesini tekrarlamanız gerekmemesidir. v3 API, son koordinatı ilk koordinata bağlayan bir çizgi çizerek tüm poligonları otomatik olarak kapatır. Aşağıdaki kod snippet'leri, Bermuda Şeytan Üçgeni'ni temsil eden bir poligon oluşturur:

var map = new GMap2(document.getElementById('map'));

map.setCenter(new GLatLng(24.886436, -70.268554), 5);

var bermudaTriangle = new GPolygon(
  [
    new GLatLng(25.774252, -80.190262),
    new GLatLng(18.466465, -66.118292),
    new GLatLng(32.321384, -64.75737),
    new GLatLng(25.774252, -80.190262)
  ],
  '#FF0000', 2, 0.8, '#FF0000', 0.35);

map.addOverlay(bermudaTriangle);

var map = new google.maps.Map(document.getElementById('map'), {
  center: new google.maps.LatLng(24.886436, -70.268554),
  mapTypeId: google.maps.MapTypeId.TERRAIN,
  zoom: 5
});

var bermudaTriangle = new google.maps.Polygon({
  paths: [
    new google.maps.LatLng(25.774252, -80.190262),
    new google.maps.LatLng(18.466465, -66.118292),
    new google.maps.LatLng(32.321384, -64.75737)
  ],
  strokeColor: '#FF0000',
  strokeWeight: 2,
  strokeOpacity: 0.8,
  fillColor: '#FF0000',
  fillOpacity: 0.35
});

bermudaTriangle.setMap(map);

Kullanıcı Tarafından Düzenlenebilir Şekiller

Çoklu çizgiler ve poligonlar kullanıcı tarafından düzenlenebilir hale getirilebilir. Aşağıdaki kod snippet'leri eşdeğerdir:

map.addOverlay(polyline);
polyline.enableEditing();

polyline.setMap(map);
polyline.setEditable(true);

Daha gelişmiş çizim özellikleri için v3 dokümanlarında yer alan Çizim Kitaplığı'na bakın.

Bilgi Pencereleri

InfoWindow, içeriği haritanın üstünde kayan bir pencerede gösterir. 2. sürüm ile 3. sürüm bilgi pencereleri arasında birkaç temel fark vardır:

• v2 API her harita için yalnızca GInfoWindow desteklerken v3 API her haritada birden fazla eşzamanlı InfoWindow destekler.
• Haritayı tıkladığınızda v3 InfoWindow açık kalır. Haritayı tıkladığınızda v2 GInfoWindow otomatik olarak kapanır. Map nesnesine bir click dinleyici ekleyerek v2 davranışını taklit edebilirsiniz.
• v3 API, sekmeli InfoWindow için yerleşik destek sağlamaz.

Zemin yer paylaşımları

Bir resmi haritaya yerleştirmek için GroundOverlay nesnesi kullanmanız gerekir. GroundOverlay sınıfının oluşturucusu, v2 ve v3'te temel olarak aynıdır: Bir resmin URL'sini ve resmin sınırlarını parametre olarak belirtir.

Aşağıdaki örnekte, Newark, NJ'nin eski bir haritası haritaya yer paylaşımı olarak yerleştirilmiştir:

var bounds = new GLatLngBounds(
    new GLatLng(40.716216, -74.213393),
    new GLatLng(40.765641, -74.139235));

var overlay = new GGroundOverlay(
    'http://lib.utexas.edu/maps/historical/newark_nj_1922.jpg',
    bounds);

map.addOverlay(overlay);

var bounds = new google.maps.LatLngBounds(
    new google.maps.LatLng(40.716216, -74.213393),
    new google.maps.LatLng(40.765641, -74.139235));

var overlay = new google.maps.GroundOverlay(
    'http://lib.utexas.edu/maps/historical/newark_nj_1922.jpg',
    bounds);

overlay.setMap(map);

Yaygın Harita Türleri

Dört temel harita türü hem sürüm 2 hem de sürüm 3'te kullanılabilir:

• MapTypeId.ROADMAP (G_NORMAL_MAP yerine) yol haritası görünümünü gösterir.
• MapTypeId.SATELLITE (G_SATELLITE_MAP yerine) Google Earth uydu görüntülerini gösterir.
• MapTypeId.HYBRID (G_HYBRID_MAP yerine) normal ve uydu görünümlerinin bir karışımını gösterir.
• MapTypeId.TERRAIN (G_PHYSICAL_MAP yerine) Arazi bilgilerine dayalı fiziksel bir harita gösterir.

Aşağıda, haritayı arazi görünümüne ayarlayan v2 ve v3 örnekleri verilmiştir:

map.setMapType(G_PHYSICAL_MAP);
    

map.setMapTypeId(google.maps.MapTypeId.TERRAIN);
    

Maps JavaScript API v3, daha az kullanılan harita türlerinde de birkaç değişiklik yaptı:

• Dünya dışındaki gök cisimleri için harita karoları v3 API'de harita türü olarak kullanılamaz ancak özel harita türleri olarak erişilebilir. Örnek olarak bu özel harita türleri örneğine bakın.
• G_SATELLITE_3D_MAP türünün v2'deki yerini v3'te özel bir harita türü almaz. Bunun yerine, bu kitaplığı kullanarak Google Earth eklentisini v3 haritalarınızda entegre edebilirsiniz.

Maksimum Yakınlaştırma Görüntüleri

Uydu görüntüleri her zaman yüksek yakınlaştırma düzeylerinde kullanılamaz. Yakınlaştırma düzeyini ayarlama<2ce> işleminden önce kullanılabilen en yüksek yakınlaştırma düzeyini bilmek isteyebilirsiniz. Bu durumda google.maps.MaxZoomService sınıfını kullanın. Bu sınıf, v2'deki GMapType.getMaxZoomAtLatLng() yönteminin yerini alır.

var point = new GLatLng(
    180 * Math.random() - 90, 360 * Math.random() - 180);
var map = new GMap2(document.getElementById("map"));
map.setUIToDefault();
map.setCenter(point);
map.setMapType(G_HYBRID_MAP);

map.getCurrentMapType().getMaxZoomAtLatLng(point,
  function(response) {
    if (response.status) {
      map.setZoom(response.zoom);
    } else {
      alert("Error in Max Zoom Service.");
    }
});

var myLatlng = new google.maps.LatLng(
    180 * Math.random() - 90, 360 * Math.random() - 180);
var map = new google.maps.Map(
  document.getElementById("map"),{
    zoom: 0,
    center: myLatlng,
    mapTypeId: google.maps.MapTypeId.HYBRID
});
var maxZoomService = new google.maps.MaxZoomService();
maxZoomService.getMaxZoomAtLatLng(
  myLatlng,
  function(response) {
    if (response.status == google.maps.MaxZoomStatus.OK) {
      map.setZoom(response.zoom);
    } else {
      alert("Error in Max Zoom Service.");
    }
});

Havadan Perspektif Görüntüleri

V3'te havadan görüntüleme etkinleştirildiğinde kontroller, desteklenen yönlerde döndürmek için ek bir ara reklamlı GLargeZoomControl3D kontrolüne sahip v2 kontrolüne benzer.

45° görüntüleme özelliğinin kullanılabildiği şehirleri desteklenen şehirler haritasında görebilirsiniz. 45° görüntüler mevcut olduğunda Maps API Uydu düğmesine bir alt menü seçeneği eklenir.