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 mình để 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 (bản đồ đường đi, 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ư 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 khái niệm lập trình JavaScript và lập trình hướng đối tượng. Từ góc nhìn của người dùng, bạn cũng nên làm quen với Maps. Có nhiều hướng dẫn về JavaScript có 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 Maps JavaScript API. Chúng tôi cũng xuất bản Tài liệu tham khảo về 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 cho thấy một bản đồ được căn giữa 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();

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();

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>

    <!-- 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>
Xem ví dụ

Thử mẫu

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

  1. Chúng ta 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 bản đồ.
  3. Chúng ta xác định hàm JavaScript tạo bản đồ trong div.
  4. Chúng ta tải API JavaScript của Maps 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 khởi động (bootstrap) để 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 phương pháp phù hợp nhất với cấu trúc của mã trong dự án.

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

Trình tải Tự thân khởi nghiệp

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();

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();

Gói trình tải MAP js-api

Sử dụng @googlemaps/js-api-loader để sử dụng MAP để tải API JavaScript của Maps. Cài đặt thông qua MAP bằ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 này cho thấy giao diện Lời hứa và lệnh 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,
  });
});

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

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 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 DOCTYPE HTML5 đơ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 ở "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 hơn với nhiều trình duyệt. DOCTYPE cũng được thiết kế để xuống cấp nhẹ một cách linh hoạt; những trình duyệt không hiểu được 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 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 được kích thước, thì chúng được giả định có kích thước 0 x 0 pixel. Vì lý do đó, chúng tôi bao gồm 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 vùng chứa bản đồ <div> (có mã nhận dạng 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><html>.

Tải Maps JavaScript API

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 tự độ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 phương pháp phù hợp nhất với cấu trúc của mã trong dự án.

Tải nội tuyến

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

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

Tải động

Để chủ động tải API JavaScript của Maps trực tiếp 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, 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 để mang lại 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 MAP với các trình duyệt 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 này cho thấy giao diện Lời hứa và lệnh 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,
  });
});

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

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 tải API JavaScript của Maps, 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ó 2 tham số: key (trong đó bạn cung cấp khoá API) và callback (trong đó bạn chỉ định tên của hàm toàn cục 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 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 API JavaScript của Maps qua URL, 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 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 của Maps chính 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 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%". Trang 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 từ phần tử chứa chúng và các 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 đồ: centerzoom.

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 đồ 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 sẽ đòi hỏi một bản đồ khổng lồ, hoặc một bản đồ nhỏ với độ phân giải rất thấp. Do đó, hình ảnh bản đồ trong Google Maps và Maps JavaScript API được chia thành các "thẻ thông tin" 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 gồm 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ể xem ở 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 JavaScript của Maps 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ề toạ độ ánh xạ và toạ độ.

Đố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 mục ánh xạ duy nhất 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 mục ánh xạ 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ử JavaScript new.

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 đồ. Nút HTML là phần tử con của đối tượng JavaScript document 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à 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 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ố (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, bản đồ bị làm tối hay hình ảnh Chế độ xem đường phố "tiêu cực" có hình mờ với dòng chữ "chỉ nhằm mục đích phát triển" có thể xuất hiện. Hành vi này thường cho biết các vấn đề về khoá API hoặc thông tin thanh toán. Để sử dụng các sản phẩm của Nền tảng Google Maps, 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ó 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 đã chỉ ra một số lỗi thường gặp và cách khắc phục 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 đề thường gặp nhất xảy ra khi 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 các tuỳ chọn bản đồ.
    • Đả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 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 để biết cách triển khai.
  • 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ợ.