Meningkatkan 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. Kini 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 berminat 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, hanya saja 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

Karena alasan performa, sebaiknya hapus pemroses peristiwa jika tidak lagi diperlukan. Menghapus pemroses peristiwa memiliki cara yang sama pada 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 menangkap 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 terhadap 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 pada 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 mencapai efek serupa 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() dari objek peta Anda. Di v3, Anda akan memodifikasi objek MapOptions yang terkait, bukan mengakses atau memodifikasi kontrol secara langsung. Contoh di bawah ini 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. Pada v2, metode addControl() mengambil parameter kedua opsional yang memungkinkan Anda menentukan posisi kontrol relatif terhadap sudut peta.

Di v3, Anda menetapkan posisi kontrol melalui properti position opsi kontrol. Pemosisian kontrol ini tidak mutlak; sebaliknya, API akan menata letak kontrol secara cerdas dengan "mengalirkan"nya di sekitar elemen peta yang sudah ada dalam batasan tertentu (misalnya ukuran peta). Hal ini memastikan kontrol default kompatibel dengan kontrol Anda. Lihat Pemosisian Kontrol di v3 untuk 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 API v2, Anda membuat subclass untuk class GControl dan menentukan pengendali untuk metode initialize() dan getDefaultPosition(). Tidak ada padanan dengan class GControl di v3. Sebaliknya, kontrol direpresentasikan sebagai elemen DOM. Untuk menambahkan kontrol kustom dengan API v3, buat struktur DOM untuk kontrol dalam 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 mempertimbangkan penerapan 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 Menghapus Overlay

Jenis objek yang diwakili oleh Overlay sama antara v2 dan v3, tetapi, mereka 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() objek overlay, dan menentukan peta yang diinginkan. Menetapkan properti peta ke null akan menghapus overlay.

Tidak ada metode clearOverlays() di v3. Jika ingin mengelola satu set overlay, Anda harus membuat array untuk menyimpan overlay tersebut. 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, lalu mengubahnya. Jika gambar 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 otomatis menetapkan ukuran ikon.

Maps JavaScript API juga menyediakan dukungan untuk ikon yang kompleks. Ikon kompleks dapat mencakup beberapa ubin, 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 ke objek berjenis Icon. Bayangan marker tidak didukung di v3.

Contoh berikut menampilkan bendera pantai di Bondi Beach di Australia, dengan bagian transparan ikon 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, serta 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 informasi selengkapnya tentang cara memuat library ini.

Contoh di bawah menggambar polyline dienkode yang sama; 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. Mirip seperti objek Polyline, objek Polygon terdiri dari serangkaian titik secara berurutan. Class Polygon v3 hampir sama dengan class GPolygon v2, dengan pengecualian penting bahwa Anda tidak perlu lagi mengulangi verteks awal di akhir jalur untuk menutup loop. API v3 akan otomatis menutup setiap poligon dengan menggambar goresan yang menghubungkan koordinat terakhir dengan 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 yang Dapat Diedit Pengguna

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

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

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

Untuk kemampuan menggambar tingkat lanjut lainnya, 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 pada setiap peta.
• InfoWindow v3 akan tetap terbuka saat Anda mengklik pada peta. GInfoWindow v2 ditutup secara otomatis saat Anda mengklik pada peta. Anda dapat mengemulasi perilaku v2 dengan menambahkan pemroses click pada objek Map.
• API v3 tidak menyediakan 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, yaitu 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 campuran 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 ditampilkan 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 Udara di v3, kontrolnya mirip dengan kontrol GLargeZoomControl3D v2, dengan interstisial tambahan kontrol Rotasi untuk memutar melalui arah yang didukung.

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