Nâng cấp ứng dụng API JavaScript cho Maps của bạn từ V2 lên V3

API JavaScript phiên bản 2 của Maps không còn hoạt động kể từ ngày 26 tháng 5 năm 2021. Kết quả là các bản đồ phiên bản 2 của trang web sẽ ngừng hoạt động và sẽ trả về lỗi JavaScript. Để tiếp tục sử dụng bản đồ trên trang web của bạn, hãy di chuyển sang API JavaScript cho Maps phiên bản 3. Hướng dẫn này sẽ giúp bạn trong suốt quá trình này.

Tổng quan

Mỗi ứng dụng sẽ có quy trình di chuyển hơi khác nhau; tuy nhiên, có một số bước phổ biến cho tất cả dự án:

  1. Nhận khoá mới. API JavaScript cho Maps hiện sử dụng Google Cloud Console để quản lý các khoá. Nếu bạn vẫn đang sử dụng khoá phiên bản 2, hãy nhớ lấy khoá API mới trước khi bắt đầu di chuyển.
  2. Cập nhật API Bootstrap. Hầu hết ứng dụng đều tải API JavaScript của Maps phiên bản 3 bằng mã sau:
    <script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>
  3. Cập nhật mã của bạn. Mức độ thay đổi cần thiết sẽ phụ thuộc rất nhiều vào ứng dụng của bạn. Những thay đổi phổ biến bao gồm:
    • Luôn tham chiếu vùng chứa tên google.maps. Ở phiên bản 3, tất cả mã API của JavaScript cho Maps được lưu trữ trong không gian tên google.maps.* thay vì không gian tên chung. Hầu hết các đối tượng cũng đã được đổi tên trong quá trình này. Ví dụ: giờ đây, bạn sẽ tải google.maps.Map thay vì GMap2.
    • Xóa mọi tệp tham chiếu đến các phương thức cũ. Một số phương thức tiện ích chung được xoá, chẳng hạn như GDownloadURL và GLog. Hãy thay thế chức năng này bằng các thư viện tiện ích của bên thứ ba hoặc xóa các tệp tham chiếu này khỏi mã của bạn.
    • (Không bắt buộc) Thêm thư viện vào mã của bạn. Nhiều tính năng đã được đưa vào các thư viện tiện ích để mỗi ứng dụng chỉ phải tải các phần của API sẽ được sử dụng.
    • (Không bắt buộc) Định cấu hình dự án để sử dụng phiên bản v3. Bạn có thể sử dụng các phần mở rộng v3 để giúp xác thực mã bằng Trình biên dịch đóng hoặc để kích hoạt tính năng tự động hoàn thành trong IDE. Tìm hiểu thêm về tính năng Biên dịch nâng cao và mở rộng.
  4. Thử nghiệm và lặp lại. Tại thời điểm này, bạn vẫn còn một số việc cần làm, nhưng tin vui là bạn sẽ nhanh chóng tiếp cận ứng dụng bản đồ v3 mới!

Những thay đổi trong phiên bản 3 của API Maps JavaScript

Trước khi lên kế hoạch di chuyển, bạn nên dành thời gian để tìm hiểu sự khác biệt giữa API JavaScript của Maps phiên bản 2 và API JavaScript phiên bản 3. Phiên bản mới nhất của API JavaScript cho Maps được viết từ đầu, tập trung vào các kỹ thuật lập trình JavaScript hiện đại, tăng cường sử dụng thư viện và đơn giản hoá một API. Nhiều tính năng mới đã được thêm vào API và một số tính năng quen thuộc đã được thay đổi hoặc thậm chí là xoá. Phần này nêu bật một số điểm khác biệt chính giữa 2 bản phát hành.

Một số thay đổi trong API phiên bản 3 bao gồm:

  • Thư viện cốt lõi đơn giản. Nhiều chức năng bổ sung đã được chuyển vào thư viện, giúp giảm thời gian tải và phân tích cú pháp API cốt lõi, cho phép bản đồ của bạn tải nhanh trên mọi thiết bị.
  • Cải thiện hiệu suất của một số tính năng, chẳng hạn như hiển thị đa giác và vị trí đánh dấu.
  • Một phương pháp mới để giới hạn mức sử dụng phía máy khách nhằm thích ứng tốt hơn với các địa chỉ dùng chung của proxy trên thiết bị di động và tường lửa của công ty.
  • Thêm khả năng hỗ trợ cho một số trình duyệt hiện đại và trình duyệt cho thiết bị di động. Chúng tôi đã ngừng hỗ trợ Internet Explorer 6.
  • Xoá nhiều lớp trình trợ giúp đa năng ( GLog hoặc GDownloadUrl). Hiện nay, nhiều thư viện JavaScript xuất sắc cung cấp các chức năng tương tự, chẳng hạn như Closed hoặc jQuery.
  • Cách triển khai Chế độ xem phố HTML5 sẽ tải trên mọi thiết bị di động.
  • Chế độ xem phố tùy chỉnh có ảnh của riêng bạn, cho phép bạn chia sẻ ảnh toàn cảnh về dốc trượt tuyết, nhà để bán hoặc các địa điểm thú vị khác.
  • Tùy chỉnh Maps theo kiểu cho phép bạn thay đổi hiển thị của các phần tử trên bản đồ cơ sở để phù hợp với kiểu hình ảnh độc đáo của bạn.
  • Hỗ trợ một số dịch vụ mới, chẳng hạn như ElevationService và Distance Matrix ma trận.
  • Dịch vụ chỉ đường được cải tiến cung cấp các tuyến đường thay thế, tối ưu hóa tuyến đường (các giải pháp gần đúng với vấn đề nhân viên bán hàng đi lại), chỉ đường đi xe đạp (với lớp xe đạp), chỉ đường phương tiện và chỉ đường có thể kéo.
  • Định dạng Mã hóa địa lý được cập nhật cung cấp thông tin loại chính xác hơn giá trị accuracy từ API Mã hóa địa lý phiên bản 2.
  • Hỗ trợ nhiều Info Windows trên một Bản đồ

Nâng cấp ứng dụng

Khoá mới của bạn

API JavaScript phiên bản 3 của Maps sử dụng một hệ thống khóa mới từ phiên bản 2. Có thể bạn đã sử dụng khoá phiên bản 3 với ứng dụng. Trong trường hợp này, bạn không cần thay đổi. Để xác minh, hãy kiểm tra URL mà từ đó bạn tải API JavaScript của Maps để xem tham số key của URL đó. Nếu giá trị khóa bắt đầu bằng ' ABQIAA&#39 ;, bạn đang sử dụng khóa v2. Nếu có khóa v2, bạn phải nâng cấp lên khóa v3 trong quá trình di chuyển để có thể:

Khóa được chuyển khi tải API Maps JavaScript v3. Tìm hiểu thêm về cách tạo khoá API.

Xin lưu ý rằng nếu bạn là khách hàng API Google Maps for Work, bạn có thể đang sử dụng mã ứng dụng khách với thông số client thay vì thông số key. Mã ứng dụng khách vẫn được hỗ trợ trong API JavaScript phiên bản 3 của Maps và không cần trải qua quy trình nâng cấp khoá.

Đang tải API

Sửa đổi đầu tiên bạn cần thực hiện đối với mã của mình bao gồm cách bạn tải API. Trong phiên bản 2, bạn tải API JavaScript của Maps thông qua yêu cầu đến http://maps.google.com/maps. Nếu đang tải Maps JavaScript API phiên bản 3, bạn cần thực hiện các thay đổi sau:

  1. Tải API từ //maps.googleapis.com/maps/api/js
  2. Xoá thông số file.
  3. Cập nhật thông số key bằng khoá phiên bản 3 mới. Khách hàng dùng API Google Maps for Work nên sử dụng thông số client.
  4. (Chỉ dành cho Gói cao cấp của Nền tảng Google Maps) Đảm bảo bạn cung cấp thông số client như được giải thích trong Hướng dẫn dành cho nhà phát triển Gói cao cấp của Nền tảng Google Maps.
  5. Hãy xoá thông số v để yêu cầu phiên bản phát hành mới nhất hoặc thay đổi giá trị của thông số này cho phù hợp với lược đồ phiên bản 3.
  6. (Không bắt buộc) Thay thế thông số hl bằng language và giữ nguyên giá trị của thông số đó.
  7. (Không bắt buộc) Thêm thông số libraries để tải thư viện không bắt buộc.

Trong trường hợp đơn giản nhất, v3 boottrap sẽ chỉ chỉ định thông số khóa API của bạn:

<script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>

Ví dụ bên dưới yêu cầu phiên bản mới nhất của API JavaScript đối với Maps phiên bản 2 bằng tiếng Đức:

<script src="//maps.google.com/maps?file=api&v=2.x&key=YOUR_API_KEY&hl=de"></script>

Ví dụ bên dưới là yêu cầu tương đương cho phiên bản 3.

<script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&language=de"></script>

Ra mắt không gian tên google.maps

Đây có thể là thay đổi đáng chú ý nhất trong API JavaScript phiên bản 3 của Maps là việc ra mắt không gian tên google.maps. Theo mặc định, API phiên bản 2 đặt tất cả đối tượng trong Không gian tên chung, điều này có thể dẫn đến việc đặt tên cho những xung đột. Trong phiên bản 3, tất cả đối tượng đều nằm trong không gian tên google.maps.

Khi di chuyển ứng dụng sang phiên bản 3, bạn sẽ phải thay đổi mã để sử dụng không gian tên mới. Rất tiếc, việc tìm kiếm "G" và thay thế bằng "google.maps." sẽ không hoàn toàn hoạt động; nhưng, đó là một quy tắc chung để áp dụng khi xem xét mã của bạn. Dưới đây là một số ví dụ về các lớp tương đương trong phiên bản 2 và v3.

phiên bản 2 phiên bản 3
GMap2 google.maps.Map
GLatLng google.maps.LatLng
GInfoWindow google.maps.InfoWindow
GMapOptions google.map.MapOptions
G_API_VERSION google.maps.version
GPolyStyleOptions google.maps.PolygonOptions
or google.maps.PolylineOptions

Xoá mã lỗi thời

API JavaScript phiên bản 3 của Maps có song song với hầu hết các chức năng trong phiên bản 2; tuy nhiên, có một số lớp không còn được hỗ trợ nữa. Trong quá trình di chuyển, bạn nên thay thế các lớp này bằng các thư viện tiện ích của bên thứ ba hoặc xóa các tệp tham chiếu này khỏi mã của bạn. Có nhiều thư viện JavaScript tuyệt vời cung cấp chức năng tương tự, chẳng hạn như Closed hoặc jQuery.

Các lớp sau đây không có song song trong API JavaScript JavaScript phiên bản 3:

GBoundsGLanguage
GBrowserIsCompatibleGLayer
GControlGLog
GControlAnchorGMercatorProjection
GControlImplGNavLabelControl
GControlPositionGObliqueMercator
GCopyrightGOverlay
GCopyrightCollectionGPhotoSpec
GDownloadUrlGPolyEditingOptions
GDraggableObjectGScreenOverlay
GDraggableObjectOptionsGStreetviewFeatures
GFactualGeocodeCacheGStreetviewLocation
GGeoAddressAccuracyGStreetviewOverlay
GGeocodeCacheGStreetviewUserPhotosOptions
GGoogleBarGTileLayerOptions
GGoogleBarAdsOptionsGTileLayerOverlayOptions
GGoogleBarLinkTargetGTrafficOverlayOptions
GGoogleBarListingTypesGUnload
GGoogleBarOptionsGXml
GGoogleBarResultListGXmlHttp
GInfoWindowTabGXslt
GKeyboardHandler

So sánh mã

Hãy so sánh hai ứng dụng khá đơn giản đã được viết bằng API v2 và v3.

<!DOCTYPE html>
<html>
  <head>
    <script src="//maps.google.com/maps?file=api&v=2&key=YOUR_API_KEY"></script>
    <style>
      html, body, #map { height: 100%; margin: 0; }
    </style>
    <script>
    function initialize() {
      if (GBrowserIsCompatible()) {
        var map = new GMap2(
            document.getElementById('map'));
        map.setCenter(new GLatLng(37.4419, -122.1419), 13);
        map.setUIToDefault();

        map.addOverlay(new GMarker(new GLatLng(37.4419, -122.1419)));

      }
    }
    </script>
  </head>
  <body onload="initialize()" onunload="GUnload()">
    <div id="map"></div>
  </body>
</html>
    
<!DOCTYPE html>
<html>
  <head>
    <script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>
    <style>
      html, body, #map { height: 100%; margin: 0; }
    </style>
    <script>
    function initialize() {
      var map = new google.maps.Map(
        document.getElementById('map'), {
          center: new google.maps.LatLng(37.4419, -122.1419),
          zoom: 13,
          mapTypeId: google.maps.MapTypeId.ROADMAP
      });

      var marker = new google.maps.Marker({
            position: new google.maps.LatLng(37.4419, -122.1419),
            map: map
      });

    }
    google.maps.event.addDomListener(window, 'load', initialize);
    </script>
  </head>
  <body>
    <div id="map"></div>
  </body>
</html>

Như bạn có thể thấy, có sự khác biệt giữa hai ứng dụng. Những thay đổi đáng chú ý bao gồm:

  • Địa chỉ mà API được tải đã thay đổi.
  • Các phương thức GBrowserIsCompatible() và GUnload() không còn bắt buộc trong phiên bản 3 và đã bị xoá khỏi API.
  • Đối tượng GMap2 được thay thế bằng google.maps.Map làm đối tượng trung tâm trong API.
  • Các thuộc tính hiện được tải thông qua lớp Tuỳ chọn. Trong ví dụ trên, chúng ta đặt 3 thuộc tính cần thiết để tải bản đồ — center, zoom và mapTypeId — thông qua đối tượng MapOptions cùng dòng.
  • Giao diện người dùng mặc định được bật theo mặc định trong phiên bản 3. Bạn có thể tắt tính năng này bằng cách đặt thuộc tính disableDefaultUI thành đúng (true) trong đối tượng MapOptions.

Tóm tắt

Đến thời điểm này, bạn đã nắm được một số điểm chính liên quan trong quá trình di chuyển từ phiên bản 2 sang phiên bản 3 của API Maps JavaScript. Bạn có thể cần biết thêm những thông tin khác, nhưng sẽ tuỳ thuộc vào đơn đăng ký của bạn. Trong các phần sau, chúng tôi đưa ra hướng dẫn di chuyển cho các trường hợp cụ thể mà bạn có thể gặp phải. Ngoài ra, có một số tài nguyên có thể giúp ích cho bạn trong quá trình nâng cấp.

Nếu bạn có vấn đề hoặc thắc mắc về bài viết này, vui lòng sử dụng đường liên kết GỬI PHẢN HỒI ở đầu trang này.

Tài liệu tham khảo chi tiết

Phần này cung cấp thông tin so sánh chi tiết về các tính năng phổ biến nhất của cả API JavaScript phiên bản 2 và phiên bản 3. Mỗi phần của tệp đối chiếu được thiết kế để đọc riêng lẻ. Bạn không nên đọc toàn bộ tài liệu tham khảo này. Thay vào đó, hãy sử dụng tài liệu này để hỗ trợ quá trình di chuyển của bạn theo từng trường hợp.

  • Sự kiện – Đăng ký và xử lý sự kiện.
  • Điều khiển – thao tác điều khiển điều khiển xuất hiện trên bản đồ.
  • Lớp phủ – thêm và chỉnh sửa đối tượng trên bản đồ.
  • Loại bản đồ – các ô tạo nên bản đồ cơ sở.
  • Lớp – thêm và chỉnh sửa nội dung dưới dạng một nhóm, chẳng hạn như các lớp KML hoặc Lớp lưu lượng truy cập.
  • Dịch vụ – hoạt động với dịch vụ mã hóa địa lý, chỉ đường hoặc Chế độ xem phố của Google.

Sự kiện

Mô hình sự kiện cho Maps JavaScript API v3 tương tự như mô hình được sử dụng trong phiên bản 2, mặc dù nhiều thay đổi đã được thay đổi.

Các chế độ kiểm soát

API JavaScript cho Maps hiển thị các thành phần điều khiển trên giao diện người dùng, cho phép người dùng tương tác với bản đồ của bạn. Bạn có thể sử dụng API để tuỳ chỉnh cách các tùy chọn điều khiển này hiển thị.

Lớp phủ

Lớp phủ phản ánh các đối tượng mà bạn "add" vào bản đồ để chỉ định các điểm, đường kẻ, khu vực hoặc bộ sưu tập các đối tượng.

Loại bản đồ

Các loại bản đồ v2 và v3 hơi khác nhau, nhưng tất cả các loại bản đồ cơ bản đều có sẵn trong cả hai phiên bản API. Theo mặc định, v2 sử dụng tiêu chuẩn "painted" ô bản đồ đường phố. Tuy nhiên, v3 yêu cầu phải cung cấp một loại bản đồ cụ thể khi tạo đối tượng google.maps.Map.

Lớp

Lớp là các đối tượng trên bản đồ bao gồm một hoặc nhiều lớp phủ. Bạn có thể điều khiển các thao tác này như một đơn vị duy nhất và thường phản ánh tập hợp các đối tượng.

Dịch vụ