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

MVC Desteği İçin Yeni Etkinlik

v3 API'si, 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 Maps JavaScript API'ye aktarılır. Bu etkinlikler, standart DOM etkinliklerinden ayrıdır.
• MVC durum değişikliği bildirimleri, Maps API nesnelerindeki değişiklikleri yansıtır ve bir property_changed kuralı kullanılarak adlandırılır.

Her Haritalar API'si nesnesi, bir dizi adlandırılmış etkinliği dışa aktarır. Belirli etkinliklerle ilgilenen uygulamalar, bu etkinlikler için etkinlik işleyicileri kaydetmeli ve bu etkinlikler alındığında kod yürütmelidir. Bu etkinliğe dayalı mekanizma, Maps JavaScript API v2 ve v3'te aynıdır. Tek fark, GEvent olan ad alanının google.maps.event olarak değiştirilmesidir:

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

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

Etkinlik İşleyicileri Kaldırma

Performansı korumak açısından, artık gerekli olmayan bir etkinlik işleyiciyi kaldırmak en iyisidir. Etkinlik işleyiciyi kaldırma işlemi v2 ve v3'te aynı şekilde yapılı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()) ileterek etkinlik işleyiciyi kaldırın.

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 Başarılı Bağımsız Değişkenleri Kullanma

Kullanıcı arayüzü etkinlikleri genellikle bir etkinlik bağımsız değişkeni iletir. Daha sonra etkinlik işleyici tarafından erişilebilir. v3'teki etkinlik bağımsız değişkenlerinin çoğu, API'deki nesneler üzerinde daha tutarlı olacak şekilde basitleştirilmiştir. (Ayrıntılar için v3 Referansı'na bakın.)

v3 etkinlik işleyicilerde overlay bağımsız değişkeni yok. Bir v3 eşlemesinde click etkinliği kaydederseniz geri çağırma, yalnızca kullanıcı temel haritayı tıkladığında gerçekleşir. Bu tıklamalara tepki vermeniz gerekirse tıklanabilir yer paylaşımlarına ek geri çağırmalar kaydedebilirsiniz.

// 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
  });
});

Denetim 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 gibi ek harita türlerini destekler.
2. v2 hiyerarşik denetimi olan GHierarchicalMapTypeControl artık kullanılamıyor. google.maps.MapTypeControlStyle.HORIZONTAL_BAR denetimini kullanarak da benzer bir efekt elde edebilirsiniz.
3. GMapTypeControl tarafından v2'de sağlanan yatay düzen, v3'te kullanılamaz.

Denetimleri Haritaya Ekleme

Maps JavaScript API v2'de, harita nesnenizin addControl() yöntemini kullanarak haritanıza denetimler ekleyebilirsiniz. v3'te, kontrollere doğrudan erişmek veya üzerinde değişiklik yapmak yerine ilişkili MapOptions nesnesini değiştirirsiniz. Aşağıdaki örnekte, aşağıdaki denetimleri eklemek için haritayı nasıl özelleştireceğiniz gösterilmektedir:

• kullanıcının mevcut harita türleri arasında geçiş yapmasını sağlayan 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);

Denetimleri Harita Üzerinde Konumlandırma

v3'te konumlandırma kontrolleri önemli ölçüde değişti. addControl() yöntemi, v2'de isteğe bağlı olarak ikinci bir parametre kullanır. Bu parametre, kontrolün haritanın köşelerine göre konumunu belirtmenize olanak tanır.

v3'te kontrolün konumunu, kontrol seçeneklerinin position özelliği aracılığıyla ayarlarsınız. Bu kontrollerin konumlandırılması mutlak değildir. Bunun yerine API, kontrolleri mevcut kısıtlamalar (harita boyutu gibi) dahilinde mevcut harita öğeleri etrafında "aktararak" akıllı bir şekilde düzenler. Böylece, varsayılan kontroller kontrollerinizle uyumlu olur. Daha fazla bilgi için v3'te Konumlandırmayı Kontrol Etme konusuna bakın.

Aşağıdaki kod, yukarıdaki örneklere göre denetimleri 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

Maps JavaScript API, özel gezinme denetimleri oluşturmanıza olanak tanır. v2 API ile kontrolleri özelleştirmek isterseniz GControl sınıfını alt sınıflara ekleyip initialize() ve getDefaultPosition() yöntemleri için işleyici tanımlarsınız. v3'teki GControl sınıfının eşdeğeri yoktur. Bunun yerine kontroller, DOM öğeleri olarak gösterilir. v3 API ile özel denetim eklemek için oluşturucuda Node alt öğesi (ör. <div> öğesi) olarak kontrol için DOM yapısı oluşturun ve tüm DOM etkinliklerini işlemek için etkinlik işleyiciler ekleyin. Haritanıza özel kontrolün bir örneğini eklemek için Node öğesini haritaların controls[position] dizisine aktarın.

Yukarıda belirtilen arayüz gereksinimlerine uyan bir HomeControl sınıfı uygulaması göz önünde bulundurulduğunda (ayrıntılar için Özel Denetimler dokümanlarına bakın), aşağıdaki kod örnekleri bir haritaya nasıl özel kontrol ekleneceğini 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);

Bindirmeleri Ekleme ve Kaldırma

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

v2 API'sindeki bindirmeler, GMap2 nesnesinin addOverlay() ve removeOverlay() yöntemleri kullanılarak haritaya eklendi ve haritadan kaldırıldı. v3'te, bir Yer Paylaşımına, ilişkili yer paylaşımı seçenekleri sınıfının map özelliği aracılığıyla bir harita atarsınız. Ayrıca, bindirme nesnesinin setMap() yöntemini çağırıp istediğiniz haritayı belirterek bir bindirmeyi doğrudan ekleyebilir veya kaldırabilirsiniz. Harita özelliğinin null olarak ayarlanması, yer paylaşımını kaldırır.

v3'te clearOverlays() yöntemi yoktur. Bir yer paylaşımı grubunu yönetmek isterseniz yer paylaşımlarını barındıracak bir dizi oluşturmanız gerekir. Bu diziyi kullanarak, dizideki her bir yer paylaşımında setMap() yöntemini çağırabilirsiniz (kaldırmanız gerekiyorsa null geçirilecektir).

Sürüklenebilir İşaretçiler

Varsayılan olarak, işaretçiler tıklanabilir ancak sürüklenemez. Aşağıdaki iki örnekte sürüklenebilir bir işaretçi eklenir:

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çinin yerine gösterilecek özel bir simge tanımlayabilirsiniz. v2'de özel görüntü kullanmak için G_DEFAULT_ICON type bölümünden GIcon örneği oluşturup bu görüntüyü değiştirebilirsiniz. Resminiz varsayılan simgeden daha büyük veya küçükse bunu bir GSize örneğiyle belirtmeniz gerekir. v3 API'sı bu işlemi biraz basitleştirir. Bunun için işaretçinin icon özelliğini özel görüntünüzün URL'sine ayarlamanız yeterlidir. API, simgeyi otomatik olarak boyutlandırır.

Maps JavaScript API, karmaşık simgeleri de destekler. Karmaşık bir simge birden çok karo, karmaşık şekiller içerebilir veya resimlerin diğer yer paylaşımlarına göre nasıl görüneceğinin "yığın sırasını" belirtebilir. v2'de bir işaretçiye şekil eklemek için her bir GIcon örneğinde ek özelliği belirtmeniz ve bunu bir GMarker oluşturucuya seçenek olarak iletmeniz gerekir. v3'te bu şekilde belirtilen simgeler, icon özelliklerini Icon türünde bir nesneye ayarlamalıdır. İş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ıklanabilir değildir:

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

Çoklu çizgi, bir LatLng dizisi ve bu konumları sıralı bir sırada bağlayan bir dizi çizgi segmentinden oluşur. v3'te bir Polyline nesnesi oluşturup görüntülemek, v2'de GPolyline nesnesi kullanmaya benzer. Aşağıdaki örnekler, Zürih'ten Sidney'e, Singapur üzerinden başlayıp 3 piksel genişliğinde, yarı şeffaf bir jeodezik çoklu çizgi çizmektedir:

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

v3'te, doğrudan kodlanmış çoklu çizgilerden Polyline nesneleri oluşturma desteği yoktur. Bunun yerine, Geometri Kitaplığı, çoklu çizgileri kodlama ve kodunu çözme yöntemleri sağlar. Bu kitaplığın nasıl yükleneceği hakkında daha fazla bilgi için v3 Maps API'deki Kitaplıklar bölümüne bakın.

Aşağıdaki örneklerde aynı kodlanmış çoklu çizgiyi çizerken v3 kodu, google.maps.geometry.encoding ad alanından decodePath() yöntemini kullanı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

Bir Poligon, kapalı döngü içindeki bir bölgeyi tanımlar. Polyline nesnesine çok benzer şekilde, Polygon nesneleri de sıralı bir dizi noktadan oluşur. v3 Polygon sınıfı, v2 GPolygon sınıfıyla büyük ölçüde aynıdır ancak döngüyü kapatmak için artık yolun sonunda başlangıç tepe noktasını tekrarlamanıza gerek kalmaz. v3 API, son koordinatı tekrar 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 yapılabilir. 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ındaki Çizim Kitaplığı bölümüne bakın.

Bilgi Pencereleri

Haritanın üst kısmındaki kayan bir pencerede InfoWindow simgesi, içeriği görüntüler. v2 ve v3 bilgi pencereleri arasında birkaç önemli fark vardır:

• v2 API, harita başına yalnızca GInfoWindow değerini, v3 API ise her haritada birden fazla eşzamanlı InfoWindow destekler.
• Haritayı tıkladığınızda InfoWindow v3 açık kalır. v2 GInfoWindow, haritayı tıkladığınızda otomatik olarak kapanır. Map nesnesine bir click işleyici ekleyerek v2 davranışını emüle edebilirsiniz.
• v3 API, sekmeli InfoWindow için yerel destek sağlamaz.

Zemin Bindirmeleri

Haritaya resim yerleştirmek için GroundOverlay nesnesi kullanmanız gerekir. GroundOverlay oluşturucu, 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, New York'un antika bir haritası bindirme 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

Hem v2 hem de v3 dört temel harita türü kullanılabilir:

• MapTypeId.ROADMAP (G_NORMAL_MAP yerine geçer) yol haritası görünümünü gösterir.
• MapTypeId.SATELLITE (G_SATELLITE_MAP yerine geçer) Google Earth uydu görüntülerini görüntüler.
• MapTypeId.HYBRID (G_HYBRID_MAP yerine geçer) normal görünüm ile uydu görünümünün karışımını gösterir.
• MapTypeId.TERRAIN (G_PHYSICAL_MAP yerine geçer), arazi bilgilerine dayalı bir fiziksel harita görüntüler.

Aşağıda, v2 ve v3'te haritayı arazi görünümüne ayarlama örneği verilmiştir:

map.setMapType(G_PHYSICAL_MAP);
    

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

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

• Earth dışındaki gök cisimleri için harita desenleri, v3 API'de harita türü olarak kullanılamaz ancak bu örnekte gösterildiği gibi özel harita türleri olarak erişilebilir.
• v3'te, v2'deki G_SATELLITE_3D_MAP türünün yerini alan özel bir harita türü yoktur. Bunun yerine, bu kitaplığı kullanarak Google Earth eklentisini v3 haritalarınıza entegre edebilirsiniz.

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

Yüksek yakınlaştırma düzeylerinde uydu görüntüleri her zaman kullanılamayabilir. Yakınlaştırma düzeyini ayarlamadan önce kullanılabilen en yüksek yakınlaştırma düzeyini öğrenmek istiyorsanız 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üler etkinleştirildiğinde, kontroller v2 GLargeZoomControl3D kontrolüne benzer ve desteklenen yönler arasında geçiş yapmak için ek bir geçiş reklamı Döndürme kontrolü içerir.

Şu anda 45° görüntülerin bulunduğu şehirleri bu haritada takip edebilirsiniz. 45° görüntüler mevcut olduğunda, Maps API Uydu düğmesine bir alt menü seçeneği eklenir.