Nâng cấp ứng dụng API JavaScript cho Maps của bạn từ phiên bản 2 lên phiên bản 3

Sự kiện mới cho dịch vụ hỗ trợ MVC

API v3 thêm một loại sự kiện mới để phản ánh các thay đổi về trạng thái MVC. Hiện có 2 loại sự kiện:

• Sự kiện của người dùng (chẳng hạn như sự kiện nhấp chuột) được truyền từ DOM đến API Maps JavaScript. Những sự kiện này riêng biệt và khác với các sự kiện DOM chuẩn.
• Thông báo về việc thay đổi trạng thái MVC phản ánh các thay đổi trong các đối tượng API Maps và được đặt tên theo quy ước property_changed.

Mỗi đối tượng của API Maps xuất một số sự kiện được đặt tên. Các ứng dụng quan tâm đến các sự kiện cụ thể phải đăng ký trình nghe sự kiện cho các sự kiện đó và thực thi mã khi nhận được các sự kiện đó. Cơ chế dựa trên sự kiện này là giống nhau trong cả API JavaScript của Maps phiên bản 2 và v3, ngoại trừ việc không gian tên đã thay đổi từ GEvent thành 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.');
});

Xoá trình xử lý sự kiện

Vì lý do về hiệu suất, tốt nhất bạn nên xoá trình nghe sự kiện khi không còn cần đến trình nghe đó. Cách xoá trình nghe sự kiện hoạt động tương tự như trong v2 và v3:

1. Khi bạn tạo một trình nghe sự kiện, một đối tượng mờ (GEventListener trong phiên bản 2, MapsEventListener trong phiên bản 3) sẽ được trả về.
2. Khi bạn muốn xoá trình nghe sự kiện, hãy chuyển đối tượng này vào phương thức removeListener() (GEvent.removeListener() trong v2 hoặc google.maps.event.removeListener() trong v3) để xoá trình nghe sự kiện.

Nghe sự kiện DOM

Nếu bạn muốn thu thập và phản hồi các sự kiện DOM (Mô hình đối tượng tài liệu), v3 sẽ cung cấp phương thức tĩnh google.maps.event.addDomListener(), tương đương với phương thức GEvent.addDomListener() trong phiên bản 2.

Sử dụng các đối số đã truyền trong sự kiện

Các sự kiện giao diện người dùng thường truyền một đối số sự kiện. Sau đó, trình nghe sự kiện có thể truy cập vào đối số này. Hầu hết các đối số sự kiện trong phiên bản 3 đã được đơn giản hoá để nhất quán hơn so với các đối tượng trong API. (Xem Tài liệu tham khảo phiên bản 3 để biết thông tin chi tiết.)

Không có đối số overlay trong trình nghe sự kiện v3. Nếu bạn đăng ký một sự kiện click trên bản đồ v3, thì lệnh gọi lại sẽ chỉ xảy ra khi người dùng nhấp vào bản đồ cơ sở. Bạn có thể đăng ký thêm lệnh gọi lại trên lớp phủ có thể nhấp nếu cần phản ứng với những lượt nhấp đó.

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

Thay đổi về loại chế độ kiểm soát

Chúng tôi đã ra mắt một số thay đổi đối với loại control bằng API phiên bản 3.

1. API phiên bản 3 hỗ trợ các loại bản đồ khác, bao gồm cả bản đồ địa hình và khả năng thêm các loại bản đồ tuỳ chỉnh.
2. Chế độ kiểm soát phân cấp v2, GHierarchicalMapTypeControl, không còn hoạt động nữa. Bạn có thể đạt được hiệu quả tương tự bằng cách sử dụng chế độ điều khiển google.maps.MapTypeControlStyle.HORIZONTAL_BAR.
3. Bố cục ngang do GMapTypeControl cung cấp trong phiên bản 2 không có trong phiên bản 3.

Thêm chế độ điều khiển vào bản đồ

Với Maps JavaScript API phiên bản 2, bạn sẽ thêm các chế độ điều khiển vào bản đồ thông qua phương thức addControl() của đối tượng bản đồ. Trong phiên bản 3, thay vì truy cập hoặc sửa đổi các chế độ điều khiển trực tiếp, bạn sẽ sửa đổi đối tượng MapOptions được liên kết. Mẫu dưới đây cho biết cách tuỳ chỉnh bản đồ để thêm các chế độ điều khiển sau:

• các nút cho phép người dùng chuyển đổi giữa các loại bản đồ có sẵn
• tỷ lệ bản đồ

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

Điều khiển vị trí trên bản đồ

Các nút điều khiển vị trí đã thay đổi rất nhiều trong phiên bản 3. Trong phiên bản 2, phương thức addControl() sẽ lấy một tham số thứ hai không bắt buộc, cho phép bạn chỉ định vị trí của thành phần điều khiển so với các góc của bản đồ.

Trong phiên bản 3, bạn có thể đặt vị trí của một chế độ điều khiển thông qua thuộc tính position của các chế độ điều khiển. Vị trí của các thành phần điều khiển này không tuyệt đối. Thay vào đó, API sẽ bố trí các thành phần điều khiển một cách thông minh bằng cách "di chuyển" chúng quanh các thành phần bản đồ hiện có trong những giới hạn nhất định (chẳng hạn như kích thước bản đồ). Điều này đảm bảo rằng các chế độ điều khiển mặc định tương thích với các chế độ điều khiển của bạn. Xem phần Kiểm soát vị trí trong phiên bản 3 để biết thêm thông tin.

Mã sau đây đặt lại vị trí các chế độ kiểm soát từ các mẫu trên:

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

Điều khiển tuỳ chỉnh

API JavaScript của Maps cho phép bạn tạo các chế độ điều khiển điều hướng tuỳ chỉnh. Để tuỳ chỉnh các chế độ điều khiển bằng API v2, bạn sẽ phân lớp con của lớp GControl và xác định các trình xử lý cho phương thức initialize() và getDefaultPosition(). Không có lớp nào tương đương với lớp GControl trong phiên bản 3. Thay vào đó, các chế độ điều khiển sẽ được biểu thị dưới dạng phần tử DOM. Để thêm một thành phần điều khiển tuỳ chỉnh bằng API v3, hãy tạo một cấu trúc DOM cho chế độ điều khiển đó trong hàm khởi tạo dưới dạng phần tử con của Node (ví dụ: phần tử <div>) và thêm trình nghe sự kiện để xử lý mọi sự kiện DOM. Đẩy Node vào mảng controls[position] của bản đồ để thêm một thực thể của thành phần điều khiển tuỳ chỉnh vào bản đồ.

Do cách triển khai lớp HomeControl tuân thủ các yêu cầu về giao diện nêu trên (xem tài liệu về Chế độ điều khiển tuỳ chỉnh để biết thông tin chi tiết), các mã mẫu sau đây cho biết cách thêm một thành phần điều khiển tuỳ chỉnh vào bản đồ.

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

Thêm và xoá lớp phủ

Các loại đối tượng mà Lớp phủ biểu thị là giống nhau giữa phiên bản 2 và phiên bản 3, nhưng được xử lý theo cách khác nhau.

Các lớp phủ trong API phiên bản 2 được thêm vào và xoá khỏi bản đồ bằng các phương thức addOverlay() và removeOverlay() của đối tượng GMap2. Trong phiên bản 3, bạn chỉ định một bản đồ cho một Lớp phủ thông qua thuộc tính map của lớp tuỳ chọn lớp phủ được liên kết. Bạn cũng có thể trực tiếp thêm hoặc xoá một lớp phủ bằng cách gọi phương thức setMap() của đối tượng lớp phủ và chỉ định bản đồ mong muốn. Việc đặt thuộc tính bản đồ thành null sẽ xóa lớp phủ.

Không có phương thức clearOverlays() nào trong phiên bản 3. Nếu muốn quản lý một tập hợp lớp phủ, bạn nên tạo một mảng để giữ các lớp phủ đó. Khi sử dụng mảng này, bạn có thể gọi setMap() trên từng lớp phủ trong mảng đó (truyền null nếu bạn cần xoá chúng).

Điểm đánh dấu có thể kéo

Theo mặc định, điểm đánh dấu có thể nhấp vào nhưng không kéo được. Hai mẫu sau đây thêm một điểm đánh dấu có thể kéo:

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

Biểu tượng

Bạn có thể xác định một biểu tượng tuỳ chỉnh để hiển thị thay cho điểm đánh dấu mặc định. Để dùng hình ảnh tuỳ chỉnh trong phiên bản 2, bạn có thể tạo một thực thể GIcon từ G_DEFAULT_ICON type và sửa đổi thực thể đó. Nếu hình ảnh lớn hơn hoặc nhỏ hơn biểu tượng mặc định, bạn phải chỉ định hình ảnh đó bằng một thực thể GSize. API v3 sẽ đơn giản hoá quy trình này một chút. Bạn chỉ cần đặt thuộc tính icon của điểm đánh dấu thành URL của hình ảnh tuỳ chỉnh và API sẽ tự động định kích thước biểu tượng.

API JavaScript của Maps cũng hỗ trợ các biểu tượng phức tạp. Một biểu tượng phức tạp có thể bao gồm nhiều ô, hình dạng phức tạp hoặc chỉ định "thứ tự ngăn xếp" thể hiện hình ảnh so với các lớp phủ khác. Để thêm hình dạng vào một điểm đánh dấu trong phiên bản 2, bạn cần chỉ định thuộc tính bổ sung trong mỗi thực thể GIcon và truyền thuộc tính này dưới dạng một tuỳ chọn đến hàm khởi tạo GMarker. Trong phiên bản 3, các biểu tượng được chỉ định theo cách này phải đặt thuộc tính icon thành một đối tượng thuộc loại Icon. Bóng đánh dấu không được hỗ trợ trong phiên bản 3.

Các ví dụ sau đây minh hoạ một lá cờ bãi biển tại Bãi biển Bondi ở Úc, trong đó biểu tượng có phần trong suốt không nhấp vào được:

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

Hình nhiều đường

Hình nhiều đường bao gồm một mảng LatLng cùng với một loạt các đoạn thẳng kết nối những vị trí đó theo trình tự có thứ tự. Việc tạo và hiển thị đối tượng Polyline trong v3 cũng tương tự như sử dụng đối tượng GPolyline trong v2. Các mẫu sau đây vẽ một hình nhiều đường trắc địa bán trong suốt, rộng 3 pixel, từ Zurich đến Sydney qua Singapore:

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

Hình nhiều đường đã mã hoá

Phiên bản 3 này không hỗ trợ việc tạo đối tượng Polyline trực tiếp từ hình nhiều dòng được mã hoá. Thay vào đó, Thư viện hình học cung cấp các phương thức để mã hoá và giải mã hình nhiều đường. Hãy xem phần Thư viện trong API Maps phiên bản 3 để biết thêm thông tin về cách tải thư viện này.

Các ví dụ dưới đây vẽ cùng một hình nhiều đường được mã hoá; mã v3 sử dụng phương thức decodePath() từ không gian tên 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);

Đa giác

Đa giác xác định một vùng trong một vòng kín. Giống như đối tượng Polyline, các đối tượng Polygon bao gồm một loạt các điểm theo thứ tự. Lớp Polygon trong phiên bản 3 rất giống với lớp GPolygon trong phiên bản 2, với một ngoại lệ đáng chú ý là bạn không còn phải lặp lại đỉnh bắt đầu ở cuối đường dẫn để đóng vòng lặp. API v3 sẽ tự động đóng mọi đa giác bằng cách vẽ một nét gạch nối toạ độ cuối cùng trở lại toạ độ đầu tiên. Các đoạn mã sau đây tạo một đa giác đại diện cho Tam giác 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);

Hình dạng có thể chỉnh sửa của người dùng

Người dùng có thể chỉnh sửa hình nhiều đường và đa giác. Các đoạn mã sau đây là tương đương:

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

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

Để sử dụng các tính năng vẽ nâng cao hơn, hãy xem Thư viện bản vẽ trong tài liệu phiên bản 3.

Cửa sổ thông tin

InfoWindow hiển thị nội dung trong một cửa sổ nổi phía trên bản đồ. Có một số khác biệt chính giữa cửa sổ thông tin trong v2 và v3:

• API v2 chỉ hỗ trợ GInfoWindow cho mỗi bản đồ, trong khi API v3 hỗ trợ nhiều InfoWindow đồng thời trên mỗi bản đồ.
• InfoWindow phiên bản 3 sẽ vẫn mở khi bạn nhấp vào bản đồ. GInfoWindow phiên bản 2 sẽ tự động đóng khi bạn nhấp vào bản đồ. Bạn có thể mô phỏng hành vi của v2 bằng cách thêm trình nghe click vào đối tượng Map.
• API v3 không cung cấp dịch vụ hỗ trợ gốc cho InfoWindow dạng thẻ.

Lớp phủ mặt đất

Để đặt hình ảnh trên bản đồ, bạn nên sử dụng đối tượng GroundOverlay. Hàm khởi tạo cho GroundOverlay về cơ bản là giống nhau trong v2 và v3: hàm này chỉ định URL của hình ảnh và ranh giới của hình ảnh làm tham số.

Ví dụ sau đây đặt một bản đồ cổ của Newark, NJ lên bản đồ dưới dạng một lớp phủ:

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

Các loại bản đồ phổ biến

Có bốn loại bản đồ cơ bản trong cả phiên bản 2 và phiên bản 3:

• MapTypeId.ROADMAP (thay thế G_NORMAL_MAP) hiển thị chế độ xem bản đồ đường.
• MapTypeId.SATELLITE (thay thế G_SATELLITE_MAP) hiển thị hình ảnh vệ tinh của Google Earth.
• MapTypeId.HYBRID (thay thế G_HYBRID_MAP) hiển thị kết hợp chế độ xem thông thường và chế độ xem vệ tinh.
• MapTypeId.TERRAIN (thay thế G_PHYSICAL_MAP) hiển thị bản đồ thực tế dựa trên thông tin địa hình.

Dưới đây là ví dụ về cách thiết lập bản đồ thành chế độ xem địa hình bằng phiên bản 2 và v3:

map.setMapType(G_PHYSICAL_MAP);
    

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

API JavaScript của Maps phiên bản 3 cũng thực hiện một vài thay đổi đối với các loại bản đồ ít phổ biến hơn:

• Các ô bản đồ cho các thiên thể khác ngoài Trái đất không được cung cấp dưới dạng loại bản đồ trong API phiên bản 3, nhưng bạn có thể truy cập vào các ô bản đồ này dưới dạng các loại bản đồ tuỳ chỉnh trong ví dụ này.
• Không có loại bản đồ đặc biệt nào trong v3 thay thế cho loại G_SATELLITE_3D_MAP từ v2. Thay vào đó, bạn có thể tích hợp trình bổ trợ Google Earth vào bản đồ phiên bản 3 bằng cách sử dụng thư viện này.

Hình ảnh thu phóng tối đa

Hình ảnh vệ tinh không phải lúc nào cũng có sẵn ở mức thu phóng cao. Nếu bạn muốn biết mức thu phóng cao nhất hiện có trước khi đặt mức thu phóng, hãy sử dụng lớp google.maps.MaxZoomService. Lớp này thay thế phương thức GMapType.getMaxZoomAtLatLng() từ phiên bản 2.

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

Hình ảnh phối cảnh từ trên không

Khi bật Hình ảnh trên không ở phiên bản 3, các chế độ điều khiển tương tự như chế độ điều khiển GLargeZoomControl3D của phiên bản 2, có thêm chế độ điều khiển Xoay vòng xen kẽ để xoay qua các hướng được hỗ trợ.

Bạn có thể theo dõi các thành phố hiện có hình ảnh 45° trên bản đồ này. Khi có hình ảnh 45°, lựa chọn trình đơn phụ sẽ được thêm vào nút Vệ tinh của API Maps.