Tài liệu tham khảo nhanh về Maps JavaScript API

Maps JavaScript API là một API web phía máy khách để tạo bản đồ 2D và 3D trên trang web, thêm điểm đánh dấu, đồ hoạ tuỳ chỉnh, ảnh động và lớp dữ liệu tương tác, đồng thời xây dựng các tính năng vị trí bằng thư viện Địa điểm.

Maps JavaScript API: thông tin chính

  • Sản phẩm: Maps JavaScript API
  • Còn được gọi là: Maps JS API, Maps JS API phiên bản 3
  • Danh mục: Maps
  • Nền tảng: JavaScript (trình duyệt)
  • Chạy trên: Ứng dụng khách (mã ứng dụng hoặc trình duyệt)
  • Giai đoạn ra mắt: GA
  • Vòng đời: Đang hoạt động
  • Tổng quan: Tổng quan về Maps JavaScript API
  • Phạm vi cung cấp theo khu vực: Toàn cầu. Phạm vi cung cấp tính năng (chẳng hạn như bản đồ 3D, thông tin giao thông, đường đi và kiểu đường ranh giới) sẽ khác nhau tuỳ theo quốc gia hoặc khu vực; Điều khoản dịch vụ của EEA áp dụng cho địa chỉ thanh toán ở Khu vực kinh tế Châu Âu. (thông tin chi tiết về phạm vi bảo hiểm)

Maps JavaScript API: trường hợp sử dụng

Sử dụng Maps JavaScript API khi:

  • Bạn cần có một bản đồ 2D hoặc 3D tương tác với các điểm đánh dấu, đồ hoạ hoặc lớp dữ liệu tuỳ chỉnh trên một trang web.
  • Bạn cần hiển thị vị trí của tài sản và đường đi theo thời gian thực từ luồng dữ liệu của riêng bạn bằng Điểm đánh dấu nâng cao và hình nhiều đường.
  • Bạn cần vẽ hàng rào địa lý (hình tròn, đa giác) và kiểm tra xem toạ độ có nằm trong hàng rào địa lý đó hay không trong trình duyệt.
  • Bạn cần có tính năng Tìm kiếm địa điểm, tự động hoàn thành hoặc Place Details phía máy khách trong một ứng dụng web thông qua Places Library.

Không sử dụng API JavaScript cho Maps khi:

  • Bạn cần nhúng bản đồ vị trí doanh nghiệp hoặc đường liên kết chỉ đường mà không cần viết JavaScript tuỳ chỉnh. Thay vào đó, hãy sử dụng Maps Embed API.
  • Bạn chỉ cần một đường liên kết để mở Google Maps có vị trí, nội dung tìm kiếm hoặc đường đi. Thay vào đó, hãy sử dụng URL của Maps.
  • Bạn cần tích hợp tính năng theo dõi đội xe đi chung xe hoặc giao hàng theo lịch với SDK Trình điều khiển di động và xác thực JWT phụ trợ. Hãy sử dụng Dịch vụ Fleet Engine.

Maps JavaScript API: thiết lập

Các gói Maps JavaScript API chính thức:

  • npm: @googlemaps/js-api-loader
  • npm: @types/google.maps
  • npm: @googlemaps/markerclusterer

Maps JavaScript API: common mistakes

  • Vấn đề: Bản đồ bị tối hoặc hình ảnh trong Chế độ xem đường phố âm bản có hình mờ kiểu hình ảnh "chỉ dành cho mục đích phát triển" xuất hiện thay vì lỗi khi khoá API hoặc thông tin thanh toán bị định cấu hình sai. Cách khắc phục: Bật tính năng thanh toán cho dự án trên đám mây, thêm một khoá API hợp lệ vào mọi yêu cầu và kiểm tra bảng điều khiển của trình duyệt để biết mã lỗi cụ thể. Hãy xem /maps/documentation/javascript/error-messages.
  • Vấn đề: Các dịch vụ cũ như PlacesService, DirectionsService và DistanceMatrixService gửi LegacyApiNotActivatedMapError đến các dự án mới chưa bật API cũ. Cách khắc phục: Sử dụng các lớp tương đương mới (lớp Place, lớp Route, lớp RouteMatrix) được hỗ trợ bởi Places API (Mới) và Routes API. Hãy xem /maps/legacy#LegacyApiNotActivatedMapError.
  • Vấn đề: Kể từ phiên bản 3.65, bản đồ vệ tinh và bản đồ kết hợp không còn chuyển sang hình ảnh 45° và map.setTilt(45) không có hiệu lực. Cách khắc phục: Sử dụng bản đồ 3D thay vì hình ảnh 45°. Xem /maps/deprecations.
  • Vấn đề: Điểm đánh dấu nâng cao yêu cầu mã bản đồ; những bản đồ được tạo mà không có mã bản đồ sẽ không thể sử dụng AdvancedMarkerElement. Cách khắc phục: Tạo mã bản đồ trong Cloud Console (hoặc sử dụng DEMO_MAP_ID để thử nghiệm) và đặt mapId trên bản đồ. Xem /maps/documentation/javascript/advanced-markers/start.

Maps JavaScript API: các tính năng cũ và không còn được dùng nữa

  • Directions Service (google.maps.DirectionsService): Ngừng hoạt động kể từ ngày 1 tháng 3 năm 2025. Lớp thay thế: Lớp Route. Triệu chứng: LegacyApiNotActivatedMapError trên các dự án chưa bật Directions API cũ. Xem hướng dẫn di chuyển.
  • Dịch vụ Ma trận khoảng cách (google.maps.DistanceMatrixService): Cũ kể từ ngày 1 tháng 3 năm 2025. Thay thế: Lớp RouteMatrix. Triệu chứng: LegacyApiNotActivatedMapError trên các dự án chưa bật Distance Matrix API cũ. Xem hướng dẫn di chuyển.
  • Dịch vụ Địa điểm (google.maps.places.PlacesService): Cũ kể từ ngày 1 tháng 3 năm 2025. Lớp thay thế: Lớp Place (Places API (Mới)). Triệu chứng: LegacyApiNotActivatedMapError trên các dự án chưa bật Places API cũ. Xem hướng dẫn di chuyển.
  • google.maps.Marker: Không dùng nữa kể từ ngày 22 tháng 2 năm 2024. Thay thế: google.maps.marker.AdvancedMarkerElement. Triệu chứng: Vẫn hoạt động và chưa có kế hoạch ngừng cung cấp; các lỗi hiện có sẽ không được khắc phục. Xem hướng dẫn di chuyển.
  • KmlLayer: Ngừng hoạt động kể từ ngày 30 tháng 4 năm 2026. Phương án thay thế: Định kiểu dựa trên dữ liệu cho tập dữ liệu hoặc trình phân tích cú pháp KML của bên thứ ba bằng Lớp dữ liệu. Triệu chứng: KmlLayer không hoạt động trong phiên bản 3.66 trở lên; phiên bản 3.65 (phiên bản cuối cùng hỗ trợ tính năng này) sẽ ngừng hoạt động vào tháng 5 năm 2027. Xem hướng dẫn di chuyển.
  • Lớp bản đồ nhiệt (thư viện trực quan hoá): Ngừng hoạt động kể từ ngày 20 tháng 5 năm 2026. Thay thế: Thư viện của bên thứ ba, chẳng hạn như deck.gl HeatmapLayer. Triệu chứng: Không còn được cung cấp kể từ tháng 5 năm 2026. Xem hướng dẫn di chuyển.
  • Thư viện bản vẽ: Ngừng hoạt động kể từ ngày 4 tháng 6 năm 2026. Thay thế: Terra Draw. Triệu chứng: Không còn được cung cấp kể từ tháng 5 năm 2026. Xem hướng dẫn di chuyển.
  • Hình ảnh 45°: Ngừng hoạt động kể từ ngày 20 tháng 5 năm 2026. Thay thế: Bản đồ 3D. Triệu chứng: map.setTilt(45) không hiệu quả; chế độ xem vệ tinh vẫn từ trên xuống. Xem hướng dẫn di chuyển.
  • google.maps.event.addDomListener() và addDomListenerOnce(): Ngừng hoạt động kể từ ngày 7 tháng 4 năm 2022. Thay thế: DOM tiêu chuẩn addEventListener().
  • Các tuỳ chọn bounds, location và radius trong Dịch vụ Place Autocomplete: Ngừng hoạt động kể từ ngày 18 tháng 5 năm 2023. Thay thế: locationBias và locationRestriction.
  • gmp-place-content-config (PlaceContentConfigElement) trong Places UI Kit: Không dùng nữa. Thay thế: Thêm trực tiếp các thành phần nội dung vào thành phần Place Details hoặc trong cấu hình Tìm kiếm địa điểm.
  • Thư viện bối cảnh địa phương: Ngừng hoạt động. Thay thế: Thư viện Địa điểm.

Những việc bạn có thể làm với Maps JavaScript API

Hãy xem hướng dẫn được liên kết bên dưới cho từng nhiệm vụ hoặc so sánh giữa các sản phẩm trong Trình khám phá chức năng.

Maps JavaScript API: Xác thực địa chỉ

Maps JavaScript API: Định kiểu dựa trên dữ liệu cho ranh giới

Maps JavaScript API: Định kiểu dựa trên dữ liệu cho tập dữ liệu

Maps JavaScript API: Tập dữ liệu

  • Thêm lớp KML vào bản đồ. Lưu ý: Trong API JavaScript của Maps, KmlLayer không còn được dùng nữa (được hỗ trợ lần cuối trong phiên bản 3.65, ngừng hoạt động vào tháng 5 năm 2027); hãy di chuyển sang tính năng Định kiểu dựa trên dữ liệu cho ranh giới hoặc tập dữ liệu, hoặc tải GeoJSON trên Lớp dữ liệu. Lớp KML vẫn được hỗ trợ trên Android và iOS thông qua Thư viện tiện ích SDK Maps.
  • Thêm lớp GeoRSS vào bản đồ. Lưu ý: Không còn được dùng trong API JavaScript của Maps (KmlLayer được hỗ trợ lần cuối trong phiên bản 3.65, ngừng hoạt động vào tháng 5 năm 2027); hãy chuyển đổi nguồn cấp dữ liệu GeoRSS sang GeoJSON và tải các nguồn cấp dữ liệu đó lên lớp Dữ liệu bằng map.data.addGeoJson().
  • Thêm dữ liệu GeoJSON vào bản đồ.

Maps JavaScript API: Chỉ đường và định tuyến

Maps JavaScript API: Độ cao

Maps JavaScript API: Fleet Engine

Maps JavaScript API: Mã hoá địa lý

Maps JavaScript API: Bản đồ

Maps JavaScript API: Chú thích trên bản đồ

Maps JavaScript API: Tạo kiểu cho bản đồ

Maps JavaScript API: Khác

Maps JavaScript API: Bản đồ 3D chân thực

Maps JavaScript API: Địa điểm

Maps JavaScript API: Places UI Kit

Maps JavaScript API: Chế độ xem đường phố