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ó 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 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 đã làm quen với các khái niệm về lập trình JavaScript và 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ó nhiều hướng dẫn về JavaScript trên web.

Tài liệu mang tính khái niệm này được thiết kế để giú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 API Maps JavaScript.

Chào mọi ngườ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 thể hiện một bản đồ có tâm điểm tại 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>

    <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ử dùng mẫu

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

  1. Chúng ta khai báo ứng dụng là HTML5 bằng cách 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 ta xác định một hàm JavaScript có chức năng tạo bản đồ trong div.
  4. Chúng tôi tải API Maps JavaScript bằng trình tải tự động 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 khởi động để tải API JavaScript của Maps. 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 một phương pháp phù hợp nhất với cấu trúc mã trong dự án.

Để biết thêm thông tin chi tiết, hãy xem phần Tải API JavaScript cho Maps.

Trình tải theo phương thức tự thân khởi nghiệp

Tải Maps JavaScript API 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 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 trình tải js-api android

Sử dụng @googlemaps/js-api-loader để sử dụng Điều hướng đến việc tải API JavaScript của Maps. Hãy cài đặt giao thức này qua TLD bằng cách sử 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 cho thấy giao diện Promise (Lời hứa) và giao diện callback. 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 của bạn dưới dạng HTML5

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

<!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", tức là ứng dụng của bạn cần tuân thủ tốt hơn trên nhiều trình duyệt. DOCTYPE cũng được thiết kế để xuống cấp nhẹ; các trình duyệt không hiểu được API này sẽ bỏ qua lớp này và dùng "chế độ tương thích ngược" để hiển thị nội dung.

Lưu ý rằng một số CSS hoạt động trong chế độ tương thích ngược sẽ 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ẹ 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 được, thì chúng sẽ được giả định là có kích thước ở mức 0 x 0 pixel. Vì lý do đó, chúng tôi sẽ đưa vào nội dung khai báo <style> sau đây:

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

Nội dung khai báo CSS này cho biết vùng chứa bản đồ <div> (có mã map) phải chiếm 100% chiều cao của phần 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>.

Đang tải API JavaScript cho Maps

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

Tải cùng dòng

Để tải Maps JavaScript API cùng dòng trong một tệp HTML, hãy thêm một 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ải động API Maps JavaScript cùng dòng bằng cách sử dụ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 cung cấp để tạo trải nghiệm tải động liền mạch hơn. Bạn có thể cài đặt phiên bản này thông qua trái với địa chỉ nhà cung cấp miền 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 cho thấy giao diện Promise (Lời hứa) và giao diện callback. 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, một số thuộc tính được đặt trên thẻ script. Bạn nên đặt thẻ này. Sau đây là nội dung giải thích về từng thuộc tính.

  • src: URL mà API JavaScript của Maps được tải, bao gồm tất cả ký hiệu và định nghĩa mà 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 khi API JavaScript của Maps tải hoàn chỉnh. Đọ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 được thực thi, tập lệnh sẽ gọi hàm được chỉ định bằng tham số callback.

Thư viện

Khi tải Maps JavaScript API qua URL, bạn có thể tuỳ ý tải các 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à các 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ừ phi bạn yêu cầu cụ thể. Để biết thêm thông tin, hãy xem phần Thư viện trong Maps JavaScript API.

Các phần tử DOM của bản đồ

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

Để bản đồ hiển thị trên một trang web, chúng tôi phải đặt trước một vị trí cho bản đồ đó. Thông thường, chúng tôi 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%". Kích thước này sẽ mở rộng cho phù hợp với kích thước trên thiết bị di động. Có thể bạn cần phải điều chỉnh 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 lấy chiều rộng từ phần tử chứa 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 cho <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 đồ: 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 đó mức 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

Cung cấp một bản đồ của toàn bộ Trái đất dưới dạng một hình ảnh duy nhất sẽ cần một bản đồ rộng lớn 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" trên bản đồ. Ở mức thu phóng thấp, một tập hợp nhỏ các ô bản đồ bao phủ một khu vực rộng; ở mức thu phóng cao hơn, các ô 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 ở mức thu phóng 0, 7 và 18.

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

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

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

Lớp JavaScript biểu thị 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 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 trên trang.) Chúng ta sẽ 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> trên 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 JavaScript và chúng ta 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 xác định một biến (có tên là map) và gán 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 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 nhất định – thường là một phần tử DIV – bằng cách sử dụng bất kỳ tham số (không bắt buộc) nào được truyề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 đồ được làm tối hoặc hình ảnh "âm" trong Chế độ xem đường phố có hình mờ "chỉ dành cho mục đích phát triển" có thể xuất hiện. Hành vi này thường cho biết có vấn đề với khoá API hoặc vấn đề về 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 vấn đề này:

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

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

  • 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 các thông tin cơ bản - một số vấn đề phổ biến nhất xảy ra với việc 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 tuỳ chọn bản đồ.
    • Đảm bảo rằng bạn đã khai báo 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 với chiều cao bằng 0 nên không hiển thị được.
    Hãy tham khảo các ví dụ của chúng tôi về cách triển khai tệp tham 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ư vấn đề có trong Công cụ cho nhà phát triển Chrome. 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ợ.