Mengupgrade Aplikasi Maps JavaScript API Anda dari V2 ke V3

Kejadian Baru untuk Dukungan MVC

API v3 menambahkan tipe kejadian baru untuk merefleksikan perubahan status MVC. Sekarang ada dua jenis peristiwa:

• Peristiwa pengguna (seperti peristiwa mouse "klik") disebarkan dari DOM ke Maps JavaScript API. Peristiwa ini terpisah dan berbeda dari peristiwa DOM standar.
• Notifikasi perubahan status MVC mencerminkan perubahan dalam objek Maps API dan diberi nama menggunakan ketentuan property_changed.

Setiap objek Maps API mengekspor sejumlah kejadian yang telah dinamai. Aplikasi yang tertarik dengan peristiwa tertentu harus mendaftarkan pemroses peristiwa untuk peristiwa tersebut dan mengeksekusi kode saat peristiwa tersebut diterima. Mekanisme berbasis peristiwa ini sama di Maps JavaScript API v2 dan v3, kecuali bahwa namespace telah berubah dari GEvent menjadi google.maps.event:

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

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

Menghapus Pemroses Peristiwa

Untuk alasan performa, sebaiknya hapus pemroses peristiwa saat tidak diperlukan lagi. Menghapus pemroses peristiwa berfungsi dengan cara yang sama di v2 dan v3:

1. Saat Anda membuat pemroses peristiwa, objek buram (GEventListener di v2, MapsEventListener di v3) akan ditampilkan.
2. Jika Anda ingin menghapus pemroses peristiwa, teruskan objek ini ke metode removeListener() (GEvent.removeListener() di v2 atau google.maps.event.removeListener() di v3) untuk menghapus pemroses peristiwa.

Memproses Peristiwa DOM

Jika Anda ingin merekam dan merespons peristiwa DOM (Document Object Model), v3 menyediakan metode statis google.maps.event.addDomListener(), yang setara dengan metode GEvent.addDomListener() di v2.

Menggunakan Argumen yang Diteruskan dalam Kejadian

Peristiwa UI sering kali meneruskan argumen peristiwa yang kemudian dapat diakses oleh pemroses peristiwa. Sebagian besar argumen peristiwa di v3 telah disederhanakan agar lebih konsisten dengan objek di API. (Lihat Referensi v3 untuk mengetahui detailnya.)

Tidak ada argumen overlay di pemroses peristiwa v3. Jika Anda mendaftarkan peristiwa click pada peta v3, callback hanya akan terjadi saat pengguna mengklik peta dasar. Anda dapat mendaftarkan callback tambahan di overlay yang dapat diklik jika perlu bereaksi terhadap klik tersebut.

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

Perubahan di Tipe Kontrol

Beberapa perubahan pada jenis control telah diperkenalkan dengan API v3.

1. API v3 mendukung jenis peta tambahan, termasuk peta medan dan kemampuan untuk menambahkan jenis peta kustom.
2. Kontrol hierarkis v2, GHierarchicalMapTypeControl, tidak lagi tersedia. Anda dapat memperoleh efek yang serupa dengan menggunakan kontrol google.maps.MapTypeControlStyle.HORIZONTAL_BAR.
3. Tata letak horizontal yang disediakan oleh GMapTypeControl di v2 tidak tersedia di v3.

Menambahkan Kontrol ke Peta

Dengan Maps JavaScript API v2, Anda akan menambahkan kontrol ke peta melalui metode addControl() objek peta. Di v3, Anda mengubah objek MapOptions terkait, bukan mengakses atau mengubah kontrol secara langsung. Contoh di bawah menunjukkan cara menyesuaikan peta untuk menambahkan kontrol berikut:

• tombol yang memungkinkan pengguna beralih antar tipe peta yang tersedia
• skala peta

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

Pemosisian Kontrol pada Peta

Pemosisian kontrol telah berubah banyak dalam v3. Di v2, metode addControl() menggunakan parameter kedua opsional yang memungkinkan Anda menentukan posisi kontrol relatif terhadap sudut peta.

Di v3, Anda menetapkan posisi kontrol melalui properti position dari opsi kontrol. Pemosisian kontrol ini tidak mutlak; sebagai gantinya, API akan menata letak kontrol secara cerdas dengan "mengalirkan"nya di sekitar elemen peta yang ada dalam batasan tertentu (seperti ukuran peta). Hal ini memastikan kontrol default kompatibel dengan kontrol Anda. Lihat Mengontrol Pemosisi di v3 untuk mengetahui informasi selengkapnya.

Kode berikut memosisikan-ulang kontrol dari contoh di atas:

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

Kontrol Kustom

Maps JavaScript API memungkinkan Anda membuat kontrol navigasi kustom. Untuk menyesuaikan kontrol dengan v2 API, Anda akan membuat subclass class GControl dan menentukan pengendali untuk metode initialize() dan getDefaultPosition(). Tidak ada yang setara dengan class GControl di v3. Sebagai gantinya, kontrol direpresentasikan sebagai elemen DOM. Untuk menambahkan kontrol kustom dengan v3 API, buat struktur DOM untuk kontrol di konstruktor sebagai turunan dari Node (misalnya, elemen <div>) dan tambahkan pemroses peristiwa untuk menangani peristiwa DOM apa pun. Kirim Node ke array controls[position] peta untuk menambahkan instance kontrol kustom ke peta Anda.

Dengan implementasi class HomeControl yang mematuhi persyaratan antarmuka yang disebutkan di atas (lihat dokumentasi Kontrol kustom untuk mengetahui detailnya), contoh kode berikut menunjukkan cara menambahkan kontrol kustom ke peta.

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

Menambahkan dan Membuang Hamparan

Jenis objek yang direpresentasikan oleh Overlay sama antara v2 dan v3, tetapi ditangani secara berbeda.

Overlay di API v2 ditambahkan ke dan dihapus dari peta menggunakan metode addOverlay() dan removeOverlay() dari objek GMap2. Di v3, Anda menetapkan peta ke Overlay melalui properti map dari class opsi overlay terkait. Anda juga dapat menambahkan atau menghapus overlay secara langsung dengan memanggil metode setMap() dari objek overlay, dan menentukan peta yang diinginkan. Menetapkan properti peta ke null akan menghapus overlay.

Tidak ada metode clearOverlays() di v3. Jika ingin mengelola kumpulan overlay, Anda harus membuat array untuk menyimpan overlay. Dengan menggunakan array ini, Anda kemudian dapat memanggil setMap() pada setiap overlay dalam array (meneruskan null jika Anda perlu menghapusnya).

Marker Dapat Diseret

Secara default, marker bisa diklik tapi tidak dapat diseret. Dua contoh berikut menambahkan penanda yang dapat ditarik:

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

Ikon

Anda bisa menetapkan ikon khusus agar ditampilkan sebagai pengganti marker default. Untuk menggunakan image kustom di v2, Anda dapat membuat instance GIcon dari G_DEFAULT_ICON type, dan mengubahnya. Jika gambar Anda lebih besar atau lebih kecil dari ikon default, Anda harus menentukannya dengan instance GSize. API v3 sedikit menyederhanakan proses ini. Cukup tetapkan properti icon penanda ke URL gambar kustom Anda, dan API akan menetapkan ukuran ikon secara otomatis.

Maps JavaScript API juga menyediakan dukungan untuk ikon yang kompleks. Ikon kompleks dapat mencakup beberapa kartu, bentuk kompleks, atau menentukan "urutan tumpukan" tampilan gambar secara relatif terhadap overlay lainnya. Untuk menambahkan bentuk ke penanda di v2, Anda harus menentukan properti tambahan di setiap instance GIcon dan meneruskannya sebagai opsi ke konstruktor GMarker. Di v3, ikon yang ditentukan dengan cara ini harus menetapkan properti icon-nya ke objek berjenis Icon. Bayangan marker tidak didukung di v3.

Contoh berikut menampilkan bendera pantai di Pantai Bondi di Australia, dengan bagian transparan ikon yang tidak dapat diklik:

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

Polyline

Polyline terdiri dari array LatLng, ditambah serangkaian segmen garis yang menghubungkan lokasi tersebut secara berurutan. Membuat dan menampilkan objek Polyline di v3 mirip dengan menggunakan objek GPolyline di v2. Contoh berikut menggambar polyline geodesi semi-transparan dengan lebar 3 piksel dari Zurich ke Sydney melalui Singapura:

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

Polyline yang Dienkode

Tidak ada dukungan di v3 untuk membuat objek Polyline secara langsung dari polyline yang dienkode. Sebagai gantinya, Library Geometri menyediakan metode untuk mengenkode dan mendekode polyline. Lihat Library di Maps API v3 untuk mengetahui informasi selengkapnya tentang cara memuat library ini.

Contoh di bawah ini menggambar polyline yang sama yang dienkode; kode v3 menggunakan metode decodePath() dari namespace google.maps.geometry.encoding.

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

Poligon

Sebuah Poligon mendefinisikan suatu region dalam loop tertutup. Sama seperti objek Polyline, objek Polygon terdiri dari serangkaian titik dalam urutan yang berurutan. Class Polygon v3 hampir sama dengan class GPolygon v2, dengan pengecualian penting bahwa Anda tidak perlu lagi mengulangi vertex awal di akhir jalur untuk menutup loop. API v3 akan otomatis menutup poligon dengan menggambar goresan yang menghubungkan koordinat terakhir kembali ke koordinat pertama. Cuplikan kode berikut membuat poligon yang mewakili Segitiga Bermuda:

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

Bentuk Dapat Diedit-Pengguna

Polyline dan poligon bisa dibuat dapat-diedit-pengguna. Cuplikan kode berikut setara:

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

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

Untuk kemampuan menggambar yang lebih canggih, lihat Library Gambar dalam dokumentasi v3.

Jendela Info

InfoWindow menampilkan konten dalam jendela mengambang di atas peta. Ada beberapa perbedaan utama antara jendela info v2 dan v3:

• API v2 hanya mendukung GInfoWindow per peta, sedangkan API v3 mendukung beberapa InfoWindow serentak di setiap peta.
• InfoWindow v3 akan tetap terbuka saat Anda mengklik peta. GInfoWindow v2 akan tertutup secara otomatis saat Anda mengklik peta. Anda dapat mengemulasi perilaku v2 dengan menambahkan pemroses click pada objek Map.
• API v3 tidak memberikan dukungan native untuk InfoWindow dengan tab.

Overlay Bumi

Untuk menempatkan gambar pada peta, Anda harus menggunakan objek GroundOverlay. Konstruktor untuk GroundOverlay pada dasarnya sama di v2 dan v3: konstruktor ini menentukan URL gambar dan batas gambar sebagai parameter.

Contoh berikut menempatkan peta antik Newark, NJ pada peta sebagai overlay:

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

Tipe Peta Biasa

Empat tipe peta dasar yang tersedia di v2 dan v3:

• MapTypeId.ROADMAP (menggantikan G_NORMAL_MAP) menampilkan tampilan peta jalan.
• MapTypeId.SATELLITE (menggantikan G_SATELLITE_MAP) menampilkan gambar satelit Google Earth.
• MapTypeId.HYBRID (menggantikan G_HYBRID_MAP) menampilkan gabungan tampilan normal dan satelit.
• MapTypeId.TERRAIN (menggantikan G_PHYSICAL_MAP) menampilkan peta fisik berdasarkan informasi medan.

Berikut adalah contoh v2 dan v3 yang menyetel peta untuk menampilkan medan:

map.setMapType(G_PHYSICAL_MAP);
    

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

Maps JavaScript API v3 juga membuat beberapa perubahan pada jenis peta yang kurang umum:

• Ubin peta untuk benda langit selain Bumi tidak tersedia sebagai jenis peta di API v3, tetapi dapat diakses sebagai jenis peta kustom seperti yang ditunjukkan dalam contoh ini.
• Tidak ada jenis peta khusus di v3 yang menggantikan jenis G_SATELLITE_3D_MAP dari v2. Sebagai gantinya, Anda dapat mengintegrasikan plugin Google Earth di peta v3 menggunakan library ini.

Maximum Zoom Imagery

Gambar satelit tidak selalu tersedia pada tingkat zoom tinggi. Jika Anda ingin mengetahui tingkat zoom tertinggi yang tersedia sebelum menetapkan tingkat zoom, gunakan class google.maps.MaxZoomService. Class ini menggantikan metode GMapType.getMaxZoomAtLatLng() dari v2.

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.");
    }
});

Gambar Perspektif Aerial

Saat mengaktifkan gambar Aerial di v3, kontrolnya mirip dengan kontrol GLargeZoomControl3D v2, dengan kontrol Rotate interstisial tambahan untuk memutar melalui arah yang didukung.

Anda dapat melacak kota tempat gambar 45° saat ini tersedia di peta ini. Jika citra 45° tersedia, opsi submenu akan ditambahkan ke tombol Satelit Maps API.