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

API JavaScript của Maps phiên bản 2 không còn hoạt động kể từ ngày 26 tháng 5 năm 2021. Do đó, các bản đồ v2 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 chuyển sang Maps JavaScript API 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 chung dành cho tất cả dự án:

  1. Mua khoá mới. API JavaScript của Maps hiện sử dụng Google Cloud Console để quản lý 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 quá trình di chuyển.
  2. Cập nhật API Tự khởi động. Hầu hết ứng dụng sẽ 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ã. Lượng thay đổi cần thiết sẽ tuỳ thuộc nhiều vào hồ sơ đăng ký của bạn. Sau đây là một số thay đổi phổ biến:
    • Luôn tham chiếu không gian tên google.maps. Trong phiên bản 3, tất cả các mã API JavaScript của Maps đều đượ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ụ: thay vì GMap2, bây giờ bạn sẽ tải google.maps.Map.
    • Xoá mọi tham chiếu đến các phương thức lỗi thời. Một số phương thức tiện ích mục đích chung đã bị xoá, chẳng hạn như GDownloadURLGLog. 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 xoá 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 đoạn mã của bạn. Nhiều tính năng đã được tách riêng vào thư viện tiện ích để mỗi ứng dụng sẽ chỉ phải tải các phần của API sẽ được dùng.
    • (Không bắt buộc) Định cấu hình dự án để sử dụng các tiện ích bên ngoài v3. Bạn có thể sử dụng các bên ngoài v3 để 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ề Chế độ biên dịch nâng cao và máy tính bên ngoài.
  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ẽ làm tốt công việc để sử dụng ứng dụng bản đồ mới phiên bản 3!

Các 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 Maps phiên bản 2 và API JavaScript Maps phiên bản 3. Phiên bản mới nhất của API JavaScript trên 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á 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í bị 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 này.

Sau đây là một số thay đổi trong API phiên bản 3:

  • Thư viện lõi đơn giản. Nhiều hàm 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 cho Core API, giú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í điểm đánh dấu.
  • Phương pháp mới đối với hạn mức sử dụng phía máy khách nhằm đáp ứng tốt hơn các địa chỉ dùng chung được proxy di động và tường lửa của công ty sử dụng.
  • Thêm tính năng hỗ trợ cho một số trình duyệt hiện đại và trình duyệt dành cho thiết bị di động. Internet Explorer 6 đã ngừng hỗ trợ.
  • Xoá nhiều lớp trình trợ giúp đa năng ( GLog hoặc GDownloadUrl). Hiện nay, có nhiều thư viện JavaScript xuất sắc cung cấp chức năng tương tự, chẳng hạn như Đóng hoặc jQuery.
  • Triển khai Chế độ xem đường phố HTML5 sẽ tải trên bất kỳ thiết bị di động nào.
  • Ảnh toàn cảnh Chế độ xem đường phố tùy chỉnh với ả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.
  • Tuỳ chỉnh Bản đồ được tạo kiểu cho phép bạn thay đổi cách hiển thị các thành phần trên bản đồ cơ sở để phù hợp với phong cách hình ảnh độc đáo của bạn.
  • Hỗ trợ một số dịch vụ mới, chẳng hạn như ElevationServiceMa trận khoảng cách.
  • Dịch vụ chỉ đường được cải tiến cung cấp các tuyến đường thay thế, tính năng tối ưu hoá tuyến đường (giải pháp gần đúng cho vấn đề của nhân viên bán hàng đi lại), chỉ đường đi xe đạp (với lớp đi xe đạp), chỉ đường phương tiện công cộng và đường đi có thể kéo.
  • Một định dạng mã hóa địa lý mới cập nhật của chúng tôi 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 Cửa sổ thông tin trên một Bản đồ

Nâng cấp ứng dụng của bạn

Chìa khoá mới của bạn

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

Khoá được truyền khi tải Maps JavaScript API phiên bản 3. Tìm hiểu thêm về cách tạo khoá API.

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

Tải API

Nội dung sửa đổi đầu tiên bạn cần thực hiện đối với mã liên quan đến 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 một 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 sẽ cần thực hiện các thay đổi sau:

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

Trong trường hợp đơn giản nhất, quy trình tự khởi động v3 sẽ chỉ chỉ định tham số khoá API:

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

Dưới đây là ví dụ về một 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

Có lẽ thay đổi đáng chú ý nhất trong API JavaScript của Maps phiên bản 3 là việc giới thiệu không gian tên google.maps. API v2 đặt tất cả đối tượng trong không gian tên chung theo mặc định. Điều này có thể dẫn đến xung đột khi đặt tên. Trong v3, mọi đố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ã để tận dụng không gian tên mới. Rất tiếc là việc tìm kiếm "G" và thay thế bằng "google.maps." sẽ không hoàn toàn hiệu quả; nhưng, đó là một nguyên tắc chung nên á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 v2 và v3.

v2 v3
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 của Maps phiên bản 3 có các chức năng tương đương trong 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 thư viện tiện ích của bên thứ ba hoặc xoá các tệp tham chiếu này khỏi mã của mình. Tồn tại nhiều thư viện JavaScript xuất sắc cung cấp chức năng tương tự, chẳng hạn như Đóng hoặc jQuery.

Các lớp sau không có song song trong API JavaScript của Maps 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 đượ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ó một vài khác biệt giữa 2 ứng dụng này. Những thay đổi đáng chú ý bao gồm:

  • Địa chỉ dùng để tải API đã thay đổi.
  • Các phương thức GBrowserIsCompatible()GUnload() đã bị xoá khỏi API không còn cần thiết trong phiên bản 3 nữa.
  • Đố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 các lớp Tuỳ chọn. Trong ví dụ trên, chúng ta đặt 3 thuộc tính bắt buộc để tải bản đồ – center, zoommapTypeId – thông qua một đối tượng MapOptions cùng dòng.
  • Theo mặc định, giao diện người dùng được bật 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 true trong đối tượng MapOptions.

Tóm tắt

Đến đây, bạn đã nắm được một số điểm chính liên quan đến việc di chuyển từ phiên bản 2 sang phiên bản 3 của API JavaScript Maps. Bạn có thể cần biết thêm thông tin, nhưng thông tin đó sẽ phụ thuộc vào ứng dụng của bạn. Trong những phần sau, chúng tôi đã đưa ra hướng dẫn di chuyển cho những trường hợp cụ thể mà bạn có thể gặp phải. Ngoài ra, cũng 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 có câu hỏi 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 cho cả phiên bản 2 và phiên bản 3 của API JavaScript của Maps. Mỗi phần của tài liệu tham khảo được thiết kế để người dùng đọc riêng. 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 theo từng trường hợp.

  • Sự kiện – đăng ký và xử lý sự kiện.
  • Thành phần điều khiển – thao tác với các thành phần điều khiển điều hướng xuất hiện trên bản đồ.
  • Lớp phủ – thêm và chỉnh sửa các đố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 theo nhóm, chẳng hạn như các lớp KML hoặc Lưu lượng truy cập.
  • Dịch vụ – hoạt động với các dịch vụ mã hoá địa lý, chỉ đường hoặc Chế độ xem đường phố của Google.

Sự kiện

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

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

API JavaScript của Maps hiển thị các điều khiể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 này để tuỳ chỉnh cách các chế độ kiểm soát này xuất hiện.

Lớp phủ

Lớp phủ phản ánh các đối tượng mà bạn "thêm" 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.

Các loại bản đồ

Các loại bản đồ có trong phiên bản 2 và v3 hơi khác nhau, nhưng tất cả các loại bản đồ cơ bản đều có trong cả hai phiên bản của API. Theo mặc định, phiên bản 2 sử dụng các ô bản đồ đường "được sơn" tiêu chuẩn. Tuy nhiên, v3 yêu cầu 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ủ. Chúng có thể được điều khiển như một đơn vị duy nhất và thường phản ánh tập hợp đối tượng.

Dịch vụ