Tổng quan

Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.
Chọn nền tảng: Android iOS JavaScript

API JavaScript cho phép bạn tùy chỉnh bản đồ bằng nội dung và hình ảnh của riêng bạn để hiển thị trên các trang web và thiết bị di động. API JavaScript cho Maps có bốn loại bản đồ cơ bản (lộ trình, vệ tinh, kết hợp và địa hình) mà bạn có thể sửa đổi bằng cách sử dụng các lớp và kiểu, các tuỳ chọn điều khiển và sự kiện, cũng như các dịch vụ và thư viện khác nhau.

Đối tượng người xem

Tài liệu này dành cho những người đã quen thuộc với các khái niệm lập trình JavaScript và lập trình hướng đối tượng. Bạn cũng đã quen thuộc với Google Maps từ góc nhìn của người dùng. Có nhiều hướng dẫn về JavaScript trên web.

Tài liệu khái niệm này được thiết kế để cho phép bạn bắt đầu khám phá và phát triển ứng dụng một cách nhanh chóng bằng API JavaScript của Maps. Chúng tôi cũng xuất bản Tài liệu tham khảo API JavaScript của Maps.

Xin chào!

Cách dễ nhất để bắt đầu tìm hiểu về API JavaScript của Maps là xem một ví dụ đơn giản. Ví dụ sau đây hiển thị một bản đồ tập trung vào Sydney, New South Wales, Úc.

TypeScript

let map: google.maps.Map;

function initMap(): void {
  map = new google.maps.Map(document.getElementById("map") as HTMLElement, {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;

JavaScript

let map;

function initMap() {
  map = new google.maps.Map(document.getElementById("map"), {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

window.initMap = initMap;

CSS

/* 
 * Always set the map height explicitly to define the size of the div element
 * that contains the map. 
 */
#map {
  height: 100%;
}

/* 
 * Optional: Makes the sample page fill the window. 
 */
html,
body {
  height: 100%;
  margin: 0;
  padding: 0;
}

HTML

<html>
  <head>
    <title>Simple Map</title>
    <script src="https://polyfill.io/v3/polyfill.min.js?features=default"></script>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <div id="map"></div>

    <!-- 
     The `defer` attribute causes the callback to execute after the full HTML
     document has been parsed. For non-blocking uses, avoiding race conditions,
     and consistent behavior across browsers, consider loading using Promises
     with https://www.npmjs.com/package/@googlemaps/js-api-loader.
    -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initMap&v=weekly"
      defer
    ></script>
  </body>
</html>
Xem ví dụ

Dùng thử mẫu

Ngay cả trong ví dụ đơn giản này, có một vài điều cần lưu ý:

  1. Chúng ta khai báo ứng dụng dưới dạng HTML5 bằng cách sử dụng phần khai báo <!DOCTYPE html>.
  2. Chúng ta tạo một phần tử div có tên "map" để giữ bản đồ.
  3. Chúng ta định nghĩa một hàm JavaScript tạo ra một bản đồ trong div.
  4. Chúng tôi tải API Maps JavaScript bằng cách sử dụng thẻ script.

Bạn có thể xem phần giải thích cho các bước này như bến dưới.

Khai báo ứng dụng của bạn là HTML5

Bạn nên khai báo DOCTYPE thực sự trong ứng dụng web của mình. Trong các ví dụ ở đây, chúng tôi đã khai báo các ứng dụng của mình là HTML5 bằng cách sử dụng HTML5 DOCTYPE đơn giản như sau:

<!DOCTYPE html>

Hầu hết trình duyệt hiện tại sẽ hiển thị nội dung được khai báo bằng DOCTYPE này trong "chế độ chuẩn" nghĩa là ứng dụng của bạn phải tuân thủ trên nhiều trình duyệt hơn. DOCTYPE cũng được thiết kế để có thể xuống cấp nhẹ; các trình duyệt không hiểu rõ nội dung này sẽ bỏ qua nội dung đó và sử dụng "quirks chế độ" để hiển thị nội dung.

Xin lưu ý rằng một số CSS hoạt động trong chế độ quirks không hợp lệ ở chế độ chuẩn. Cụ thể, tất cả các kích thước dựa trên tỷ lệ phần trăm phải kế thừa từ các phần tử khối mẹ và nếu bất kỳ đối tượng cấp trên nào trong số đó không chỉ định kích thước, chúng sẽ được giả định là có kích thước 0 x 0 pixel. Vì lý do đó, chúng tôi đưa vào nội dung khai báo <style> sau:

<style>
  #map {
    height: 100%;
  }
  html, body {
    height: 100%;
    margin: 0;
    padding: 0;
  }
</style>

Khai báo CSS này cho biết rằng vùng chứa bản đồ <div> (có mã map) sẽ chiếm 100% chiều cao của phần nội dung HTML. Xin lưu ý rằng chúng tôi cũng phải khai báo cụ thể những tỷ lệ phần trăm đó cho <body><html>.

Tải API JavaScript cho Maps

API JavaScript cho Maps được tải bằng thẻ script. Bạn có thể thêm thẻ này cùng dòng trong tệp HTML hoặc sử dụng tệp JavaScript riêng. Bạn nên xem lại cả hai phương pháp và chọn phương thức phù hợp nhất với cấu trúc mã trong dự án của bạn.

Đang tải cùng dòng

Để tải API JavaScript của Maps trong dòng trong tệp HTML, hãy thêm thẻ script như được hiển thị bên dưới.

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap">
</script>

Tải động

Để chủ động tải API JavaScript cho nội tuyến bằng cách sử dụng tệp JavaScript riêng, hãy xem ví dụ bên dưới. Cách tiếp cận này cho phép bạn xử lý tất cả mã để làm việc với API từ một tệp .js riêng và tương đương với việc thêm thẻ tập lệnh cùng dòng.

// Create the script tag, set the appropriate attributes
var script = document.createElement('script');
script.src = 'https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap';
script.async = true;

// Attach your callback function to the `window` object
window.initMap = function() {
  // JS API is loaded and available
};

// Append the 'script' element to 'head'
document.head.appendChild(script);
      

Tải động

Gói @googlemaps/js-api-loader có sẵn để tạo ra trải nghiệm tải động liền mạch hơn. Bạn có thể cài đặt giải pháp này thông qua NPM bằng cách sau:

npm install @googlemaps/js-api-loader

Gói này có thể được nhập vào ứng dụng với:

import { Loader } from "@googlemaps/js-api-loader"

Trình tải này hiển thị giao diện Hứa hẹn và gọi lại. Phần sau đây minh hoạ cách sử dụng phương thức Lời hứa mặc định load().

TypeScript

const loader = new Loader({
  apiKey: "YOUR_API_KEY",
  version: "weekly",
  ...additionalOptions,
});

loader.load().then(() => {
  map = new google.maps.Map(document.getElementById("map") as HTMLElement, {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
});

JavaScript

const loader = new Loader({
  apiKey: "YOUR_API_KEY",
  version: "weekly",
  ...additionalOptions,
});

loader.load().then(() => {
  map = new google.maps.Map(document.getElementById("map"), {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
});

Thuộc tính thẻ tập lệnh

Lưu ý trong các ví dụ ở trên, bạn nên đặt một số thuộc tính trên thẻ script. Sau đây là nội dung giải thích về từng thuộc tính.

  • src: URL tải API JavaScript cho Maps, bao gồm tất cả các ký hiệu và định nghĩa mà bạn cần để sử dụng API JavaScript cho Maps. URL trong ví dụ này có hai tham số: key, trong đó bạn cung cấp khoá API và callback, trong đó bạn chỉ định tên của một hàm toàn cục được gọi sau khi API JavaScript của Maps tải hoàn toàn. Đọc thêm về các tham số URL.
  • async: Yêu cầu trình duyệt tải xuống và thực thi tập lệnh một cách không đồng bộ. Khi tập lệnh được thực thi, tập lệnh đó sẽ gọi hàm được chỉ định bằng cách sử dụng tham số callback.

Thư viện

Khi tải API Maps JavaScript qua URL, bạn có thể tuỳ ý tải thư viện bổ sung thông qua việc sử dụng tham số URL libraries. Thư viện là các mô-đun mã cung cấp chức năng bổ sung cho API JavaScript chính của Maps nhưng không tải được trừ khi bạn yêu cầu cụ thể. Để biết thêm thông tin, hãy xem phần Thư viện trong API JavaScript của Maps.

Tải đồng bộ API

Trong thẻ script tải API JavaScript của Maps, bạn có thể bỏ qua thuộc tính defer và tham số callback. Điều này sẽ khiến quá trình tải API bị chặn cho đến khi API được tải xuống.

Việc này có thể sẽ làm chậm tốc độ tải trang. Tuy nhiên, điều này có nghĩa là bạn có thể viết các thẻ tập lệnh tiếp theo giả định rằng API đã được tải.

Liên kết các phần tử DOM

<div id="map"></div>

Để bản đồ hiển thị trên trang web, chúng tôi phải đặt trước một vị trí cho bản đồ đó. Thông thường, chúng ta thực hiện việc này bằng cách tạo một phần tử div có tên và lấy thông tin tham chiếu đến phần tử này trong mô hình đối tượng tài liệu (DOM) của trình duyệt.

Trong ví dụ trên, chúng tôi đã sử dụng CSS để đặt chiều cao của div bản đồ thành "100%". Tệp này sẽ mở rộng để vừa với kích thước trên thiết bị di động. Bạn có thể cần điều chỉnh các giá trị chiều rộng và chiều cao dựa trên kích thước màn hình và khoảng đệm của trình duyệt. Lưu ý rằng các div thường lấy chiều rộng của chúng từ phần tử chứa, và các div trống thường có chiều cao là 0. Vì lý do này, bạn phải luôn đặt chiều cao trên <div> một cách rõ ràng.

Tùy chọn bản đồ

Có hai tùy chọn bắt buộc cho mỗi bản đồ: centerzoom.

map = new google.maps.Map(document.getElementById('map'), {
  center: {lat: -34.397, lng: 150.644},
  zoom: 8
});

Mức thu phóng

Độ phân giải ban đầu để hiển thị bản đồ được đặt bằng thuộc tính zoom, trong đó mức thu phóng 0 tương ứng với bản đồ Trái đất được thu nhỏ hoàn toàn và mức thu phóng lớn hơn sẽ phóng to ở độ phân giải cao hơn.

zoom: 8

Việc cung cấp một bản đồ toàn bộ Trái Đất dưới dạng một hình ảnh đơn lẻ sẽ cần một bản đồ khổng lồ hoặc một bản đồ nhỏ có độ phân giải rất thấp. Do đó, hình ảnh bản đồ trong Google Maps và API JavaScript của Maps được chia thành các cấp bản đồ "tiles" và "zoom." Ở mức thu phóng thấp, một tập hợp các ô bản đồ sẽ bao phủ một khu vực rộng; ở các mức thu phóng cao hơn, các ô này có độ phân giải cao hơn và bao phủ một khu vực nhỏ hơn. Danh sách sau đây cho thấy mức độ chi tiết gần đúng mà bạn có thể thấy ở mỗi mức thu phóng:

  • 1: Thế giới
  • 5: Vùng đất/lãnh thổ
  • 10: Thành phố
  • 15: Đường phố
  • 20: Tòa nhà

Ba hình ảnh sau phản ánh cùng vị trí của Tokyo ở mức thu phóng 0, 7 và 18.

Để biết thông tin về cách API JavaScript tải bản đồ các ô theo mức thu phóng hiện tại, hãy xem hướng dẫn về bản đồ toạ độ và bản đồ ô.

Đối tượng bản đồ

map = new google.maps.Map(document.getElementById("map"), {...});

Lớp JavaScript đại diện cho một bản đồ là lớp Map. Các đối tượng của lớp này xác định một bản đồ duy nhất trên một trang. (Bạn có thể tạo nhiều bản sao của lớp này – mỗi đối tượng sẽ xác định một bản đồ riêng trên trang.) Chúng ta tạo một thực thể mới của lớp này bằng cách sử dụng toán tử new của JavaScript.

Khi tạo một thực thể bản đồ mới, bạn sẽ chỉ định một phần tử HTML <div> trong trang làm vùng chứa cho bản đồ. Các nút HTML là phần tử con của đối tượng document trên JavaScript và chúng ta thu thập dữ liệu tham chiếu đến phần tử này thông qua phương thức document.getElementById().

Mã này xác định một biến (có tên là map) và chỉ định biến đó cho một đối tượng Map mới. Hàm Map() được gọi là một hàm khởi tạo (constructor) và định nghĩa của hàm này như sau:

Hàm dựng Nội dung mô tả
Map(mapDiv:Node, opts?:MapOptions ) Tạo một bản đồ mới bên trong vùng chứa HTML đã cho – thường là một phần tử DIV – sử dụng mọi thông số (không bắt buộc) được chuyển.

Khắc phục sự cố

Khoá API và Lỗi thanh toán

Trong một số trường hợp nhất định, bản đồ bị làm tối hoặc 'phủ định' hình ảnh Chế độ xem phố, được làm mờ bằng văn bản "chỉ cho mục đích phát triển" có thể được hiển thị. Hành vi này thường cho thấy có sự cố với khóa API hoặc thanh toán. Để sử dụng các sản phẩm của Google Maps Platform, bạn phải bật tính năng thanh toán trên tài khoản của mình và tất cả yêu cầu phải có khóa API hợp lệ. Quy trình sau sẽ giúp bạn khắc phục vấn đề này:

Nếu mã của bạn không hoạt động:

Để giúp bạn thiết lập và chạy mã bản đồ, Brendan Kenny và Mano Marks chỉ ra một số lỗi phổ biến và cách khắc phục chúng trong video này.

  • Tìm lỗi chính tả. Hãy nhớ rằng JavaScript là một ngôn ngữ có phân biệt chữ hoa chữ thường.
  • Kiểm tra thông tin cơ bản – một số vấn đề phổ biến nhất xảy ra trong quá trình tạo bản đồ ban đầu. Chẳng hạn như:
    • Xác nhận rằng bạn đã chỉ định các thuộc tính zoomcenter trong tùy chọn bản đồ của mình.
    • Hãy đảm bảo rằng bạn đã khai báo phần tử div mà bản đồ sẽ xuất hiện trên màn hình.
    • Đảm bảo rằng phần tử div cho bản đồ có chiều cao. Theo mặc định, các phần tử div được tạo với chiều cao là 0 và do đó không hiển thị.
    Hãy tham khảo ví dụ của chúng tôi về cách triển khai tệp đối chiếu.
  • Sử dụng trình gỡ lỗi JavaScript để giúp xác định các vấn đề, chẳng hạn như trình gỡ lỗi có sẵn trong Công cụ dành cho nhà phát triển Chrome. Hãy bắt đầu bằng cách tìm lỗi trong bảng điều khiển JavaScript.
  • Đăng câu hỏi lên Stack Overflow. Bạn có thể xem hướng dẫn về cách đăng những câu hỏi hay trên trang Hỗ trợ.