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

Sự kiện mới để hỗ trợ MVC

API phiên bản 3 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ó hai loại sự kiện:

• Các sự kiện của người dùng (chẳng hạn như sự kiện chuột "nhấp") được truyền từ DOM đến API JavaScript của Maps. Các sự kiện này tách biệt và khác với các sự kiện DOM tiêu chuẩn.
• Thông báo 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 Maps API sẽ 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ể nên đă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ế do sự kiện điều khiển này giống nhau trong cả API JavaScript của Maps phiên bản 2 và 3, 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 nghe sự kiện

Vì lý do 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 thiết nữa. Việc xoá trình nghe sự kiện cũng hoạt động theo cách tương tự trong phiên bản 2 và phiên bản 3:

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 truyền đối tượng này đến phương thức removeListener() (GEvent.removeListener() trong phiên bản 2 hoặc google.maps.event.removeListener() trong phiên bản 3) để xoá trình nghe sự kiện.

Theo dõi sự kiện DOM

Nếu bạn muốn ghi lại 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 v2.

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

Các sự kiện trên giao diện người dùng thường truyền một đối số sự kiện mà sau đó trình nghe sự kiện có thể truy cập. 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 với các đối tượng trong API. (Hãy tham khảo Tài liệu tham khảo v3 để biết thông tin chi tiết.)

Không có đối số overlay nào tồn tại trong trình nghe sự kiện phiên bản 3. Nếu bạn đăng ký một sự kiện click trên bản đồ v3, 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 các lệnh gọi lại trên lớp phủ có thể nhấp nếu cần phản ứng với các 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ế độ điều khiển

Một số thay đổi đối với các loại control đã được giới thiệu với API v3.

1. API phiên bản 3 hỗ trợ thêm các loại bản đồ, 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. Bạn không thể sử dụng chế độ điều khiển phân cấp v2, GHierarchicalMapTypeControl nữa. Bạn có thể đạt được hiệu quả tương tự bằng cách sử dụng thành phần đ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 các nút đ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 trực tiếp các thành phần điều khiển, bạn sẽ sửa đổi đối tượng MapOptions được liên kết. Ví dụ dưới đây cho thấy 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 chế độ đ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 đặt vị trí của một thành phần điều khiển thông qua thuộc tính position của các tuỳ chọn điều khiển. Vị trí của các chế độ điều khiển này không phải là tuyệt đối; thay vào đó, API sẽ bố trí các chế độ điều khiển một cách thông minh bằng cách "lưu chuyển" các chế độ điều khiển đó xung quanh các phần tử bản đồ hiện có trong các quy tắc ràng buộc nhất định (chẳng hạn như kích thước bản đồ). Điều này giúp đả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. Hãy 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 sẽ định vị lại các thành phần điều khiển 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);

Chế độ đ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ẽ tạo lớp con cho lớp GControl và xác định trình xử lý cho các 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 thành phần điều khiển đượ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 thành phần đ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 đồ.

Với việc 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 chế độ đ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 được biểu thị bằng một Lớp phủ giống nhau giữa phiên bản 2 và 3, tuy nhiên, các loại đối tượng này được xử lý theo cách khác nhau.

Các lớp phủ trong API v2 đã đượ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á 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ẽ xoá 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 để chứa 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 (chuyển null nếu cần xoá các lớp phủ đó).

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

Theo mặc định, bạn có thể nhấp vào điểm đánh dấu nhưng không thể kéo điểm đánh dấu. 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. Để sử 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 phiên bản 3 đơn giản hoá một chút quy trình này. 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, API sẽ tự động định cỡ biểu tượng.

Maps JavaScript API 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 thẻ thông tin, hình dạng phức tạp hoặc chỉ định "thứ tự xếp chồng" của cách hình ảnh hiển thị tương ứng với các lớp phủ khác. Để thêm hình dạng vào đ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 của điểm đánh dấu không được hỗ trợ trong phiên bản 3.

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

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

Một đa tuyến 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 các vị trí đó theo trình tự có thứ tự. Việc tạo và hiển thị đối tượng Polyline trong phiên bản 3 tương tự như việc sử dụng đối tượng GPolyline trong phiên bản 2. Các mẫu sau đây vẽ một đường đa giác hình học 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 không hỗ trợ việc tạo đối tượng Polyline trực tiếp từ các đường đa giác đượ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ã đa tuyến. 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ụ bên dưới vẽ cùng một đường đa tuyến đượ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 lặp kín. Tương tự như đối tượng Polyline, các đối tượng Polygon bao gồm một loạt các điểm theo trình tự đã sắp xếp. Lớp Polygon v3 rất giống với lớp GPolygon v2, ngoại trừ một điểm đá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 nối toạ độ cuối cùng vớ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 đa tuyến và đa giác. Các đoạn mã sau đây tương đương với nhau:

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

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

Để biết thêm các tính năng vẽ nâng cao, hãy xem Thư viện vẽ trong tài liệu v3.

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ố điểm khác biệt chính giữa cửa sổ thông tin phiên bản 2 và phiên bản 3:

• API phiên bản 2 chỉ hỗ trợ GInfoWindow trên mỗi bản đồ, trong khi API phiên bản 3 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 trên đối tượng Map.
• API v3 không hỗ trợ gốc cho InfoWindow có 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. Về cơ bản, hàm khởi tạo cho GroundOverlay giống nhau trong phiên bản 2 và 3: hàm này chỉ định URL của hình ảnh và ranh giới của hình ảnh dưới dạng tham số.

Ví dụ sau đây đặt một bản đồ cổ của Newark, New Jersey trên bản đồ dưới dạng 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ả phiên bản 2 và 3 đều có 4 loại bản đồ cơ bản:

• 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ị chế độ xem 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ề v2 và v3 thiết lập bản đồ thành chế độ xem địa hình:

map.setMapType(G_PHYSICAL_MAP);
    

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

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

• Thẻ thông tin bản đồ cho các thiên thể khác với Trái Đất không có sẵn dưới dạng loại bản đồ trong API phiên bản 3, nhưng có thể được truy cập dưới dạng loại bản đồ tuỳ chỉnh như trong ví dụ này.
• Không có loại bản đồ đặc biệt nào trong phiên bản 3 thay thế loại G_SATELLITE_3D_MAP từ phiên bản 2. 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

Không phải lúc nào bạn cũng có thể xem hình ảnh vệ tinh ở mức thu phóng cao. Nếu bạn muốn biết mức thu phóng cao nhất có sẵn 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 tính năng Hình ảnh trên không trong phiên bản 3, các chế độ điều khiển sẽ tương tự như chế độ điều khiển GLargeZoomControl3D trong phiên bản 2, với một chế độ điều khiển Xoay xen kẽ bổ sung để xoay theo 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°, một tuỳ chọn trình đơn phụ sẽ được thêm vào nút Vệ tinh của Maps API.