Tổng quan

Chọn nền tảng: Android iOS JavaScript

API JavaScript của Maps cho phép bạn tuỳ 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 của Maps có 4 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 chế độ điều khiển và sự kiện cũng như nhiều dịch vụ và thư viện.

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

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

Tài liệu khái niệm này được thiết kế để cho phép bạn nhanh chóng bắt đầu khám phá và phát triển các ứng dụ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 về API Maps JavaScript.

Xin chào, thế giới

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 đồ ở giữa Sydney, New South Wales, Úc.

TypeScript

let map: google.maps.Map;
async function initMap(): Promise<void> {
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
  map = new Map(document.getElementById("map") as HTMLElement, {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

initMap();
index.ts

JavaScript

let map;

async function initMap() {
  const { Map } = await google.maps.importLibrary("maps");

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

initMap();
index.js

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

style.css

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>

    <!-- prettier-ignore -->
    <script>(g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})
        ({key: "AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg", v: "weekly"});</script>
  </body>
</html>
index.html
Xem ví dụ

Thử mẫu

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

  1. Chúng tôi khai báo ứng dụng là HTML5 bằng cách sử dụng nội dung khai báo <!DOCTYPE html>.
  2. Chúng ta tạo một phần tử div có tên là "map" để lưu giữ bản đồ.
  3. Chúng tôi xác định một hàm JavaScript tạo bản đồ trong div.
  4. Chúng tôi tải Maps JavaScript API bằng trình tải khởi động.

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

Tải Maps JavaScript API

Bạn nên sử dụng trình tải tự khởi động để tải API Maps JavaScript. Trình tải API JS cũng được cung cấp để thay thế. Bạn nên xem xét cả hai phương pháp và chọn phương pháp phù hợp nhất với cấu trúc mã trong dự án của mình.

Để biết thêm thông tin chi tiết, hãy xem bài viết Tải Maps JavaScript API.

Trình tải tự khởi động

Tải API JavaScript của Maps bằng cách thêm trình tải khởi động cùng dòng vào mã xử lý ứng dụng của bạn, như minh hoạ trong đoạn mã sau:

<script>
  (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
    key: "YOUR_API_KEY",
    v: "weekly",
    // Use the 'v' parameter to indicate the version to use (weekly, beta, alpha, etc.).
    // Add other bootstrap parameters as needed, using camel case.
  });
</script>

Để tải thư viện trong thời gian chạy, hãy sử dụng toán tử await để gọi importLibrary() từ trong một hàm không đồng bộ, như minh hoạ dưới đây:

TypeScript

let map: google.maps.Map;
async function initMap(): Promise<void> {
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
  map = new Map(document.getElementById("map") as HTMLElement, {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

initMap();
index.ts

JavaScript

let map;

async function initMap() {
  const { Map } = await google.maps.importLibrary("maps");

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

initMap();
index.js

Gói gradle js-api-loader

Sử dụng @googlemaps/js-api-loader để sử dụng SSID nhằm tải API Maps JavaScript. Cài đặt thông qua SSID bằng cách dùng lệnh sau:

npm install @googlemaps/js-api-loader

Bạn có thể nhập gói này vào ứng dụng bằng:

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

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

TypeScript

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

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

JavaScript

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

loader.load().then(async () => {
  const { Map } = await google.maps.importLibrary("maps");

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

index.js

Khai báo ứng dụng dưới dạng HTML5

Bạn nên khai báo DOCTYPE đúng trong ứng dụng web. Trong những 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 DOCTYPE HTML5 đơn giản như sau:

<!DOCTYPE html>

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

Lưu ý rằng một số CSS hoạt động ở chế độ tương thích ngược không hợp lệ ở chế độ tiêu 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ẹ. Nếu có bất kỳ đối tượng cấp trên nào trong số đó không chỉ định được kích thước, thì kích thước 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ã nhận dạng là map) phải chiếm 100% chiều cao của nội dung HTML. Xin lưu ý rằng chúng ta cũng phải khai báo cụ thể các tỷ lệ phần trăm đó cho <body> và <html>.

Tải Maps JavaScript API

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

Tải nội tuyến

Để tải API JavaScript Maps cùng dòng trong tệp HTML, hãy thêm thẻ script như minh hoạ dưới đây.

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

Tải động

Để tự động tải API JavaScript Maps cùng dòng bằng một tệp JavaScript riêng, hãy xem ví dụ bên dưới. Phương pháp này cho phép bạn xử lý tất cả mã để làm việc với API qua một tệp .js riêng biệt 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 trải nghiệm tải động liền mạch hơn. Bạn có thể cài đặt ứng dụng này thông qua ALIAS với những nội dung sau:

npm install @googlemaps/js-api-loader

Bạn có thể nhập gói này vào ứng dụng bằng:

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

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

TypeScript

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

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

JavaScript

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

loader.load().then(async () => {
  const { Map } = await google.maps.importLibrary("maps");

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

index.js

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 nơi API Maps JavaScript được tải, bao gồm tất cả ký hiệu và định nghĩa bạn cần để sử dụng API JavaScript của 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 chung sẽ được gọi sau khi API JavaScript của Maps) tải hoàn toàn. Đọc thêm về 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 đượ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 JavaScript của Maps thông qua URL này, bạn có thể tuỳ ý tải thư viện bổ sung bằng cách sử dụng toán tử await để gọi importLibrary() từ trong một hàm không đồng bộ. Thư viện là những mô-đun mã cung cấp chức năng bổ sung cho API JavaScript chính của Maps, nhưng sẽ không được tải trừ khi bạn yêu cầu cụ thể. Để biết thêm thông tin, hãy xem bài viết Thư viện trong API JavaScript của Maps.

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 làm điều 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%". Kích thước này sẽ mở rộng cho 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 div thường có chiều rộng từ phần tử chứa chúng và div trống thường có chiều cao bằng 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 tuỳ chọn bắt buộc cho mỗi bản đồ: center và zoom.

map = new 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ởi thuộc tính zoom, trong đó tính năng thu phóng 0 tương ứng với bản đồ của Earth đượ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 bản đồ toàn bộ Trái đất dưới dạng một hình ảnh duy nhất sẽ đòi hỏi 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 "ô" và "mức thu phóng" bản đồ. Ở mức thu phóng thấp, một tập hợp nhỏ các ô bản đồ sẽ bao phủ một khu vực rộng; ở mức thu phóng cao hơn, các ô này sẽ 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ục địa
  • 10: Thành phố
  • 15: Đường phố
  • 20: Toà nhà

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

Để biết thông tin về cách API Maps JavaScript tải thẻ thông tin dựa trên mức thu phóng hiện tại, hãy xem hướng dẫn về cách ánh xạ và toạ độ thẻ thông tin.

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

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

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

Khi tạo một phiên bản 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à con của đối tượng document JavaScript và chúng tôi lấy thông tin tham chiếu đến phần tử này thông qua phương thức document.getElementById().

Mã này định nghĩa một biến (có tên là map) và chỉ định biến đó cho đối tượng Map mới. Hàm Map() được gọi là hàm khởi tạo 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à phần tử DIV – bằng cách sử dụng bất kỳ tham số nào (không bắt buộc) được truyền.

Khắc phục sự cố

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

Trong một số trường hợp, một bản đồ bị tối màu hay hình ảnh Chế độ xem đường phố "tiêu cực" có hình mờ với dòng chữ "chỉ dành cho mục đích phát triển" có thể xuất hiện. Hành vi này thường chỉ ra các vấn đề với khoá API hoặc việc thanh toán. Để sử dụng các sản phẩm trên Nền tảng Google Maps, bạn phải bật tính năng thanh toán trong tài khoản của mình và tất cả yêu cầu phải bao gồm một khoá API hợp lệ. Quy trình sau đây sẽ giúp khắc phục sự cố 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 sẽ 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à 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 đề thường gặp 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 zoom và center trong các tuỳ chọn bản đồ.
    • Hãy đảm bảo rằng bạn đã khai báo một phần tử div mà trong đó 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 có chiều cao bằng 0 và do đó sẽ không hiển thị.
    Hãy tham khảo các ví dụ của chúng tôi để cách triển khai tài liệu tham khảo.
  • Sử dụng trình gỡ lỗi JavaScript để giúp xác định các vấn đề, chẳng hạn như vấn đề có trong Công cụ 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. Hướng dẫn về cách đăng câu hỏi hay có trên trang Hỗ trợ.