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 thành phầ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 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 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 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 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 đồ có tâm điểm là 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ử đọc 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 bản đồ.
  3. Chúng ta xác định một hàm JavaScript tạo bản đồ trong div.
  4. Chúng tôi tải API JavaScript cho Maps bằng cách sử dụng trình tải khởi động (bootstrap).

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 API Maps JavaScript

Bạn nên sử dụng trình tải khởi động (bootstrap) để tải API JavaScript cho Maps. Trình tải API JS cũng được cung cấp dưới dạng một giải phá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ách 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 API JavaScript của Maps.

Trình tải Bootstrap

Tải API JavaScript cho 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, 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 Ctrl

Sử dụng @googlemaps/js-api-loader để sử dụng Hangouts nhằm tải API JavaScript cho Maps. Cài đặt phiên bản này thông qua Hangouts 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 hiển thị 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,
  });
});
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 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 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ẹ một cách linh hoạt. Các trình duyệt không hiểu mã này sẽ bỏ qua mã này và sử 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 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 gốc. 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ì các 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 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 rằng 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>.

Tải API Maps JavaScript

API JavaScript của Maps được tải bằng cách sử dụng thẻ script, có thể được thêm vào cùng dòng trong tệp HTML của bạn 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 cho Maps cùng dòng trong một tệp HTML, hãy thêm thẻ script như 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 Maps JavaScript nội tuyến 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ả các mã để làm việc với API từ một tệp .js riêng biệt và tương đương với việc thêm thẻ tập lệnh nội tuyến.

// 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 trình phân tích cú pháp thông qua Percent với các tiện ích 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 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,
  });
});
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 mà 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 cho Maps. URL trong ví dụ này có hai tham số: key (trong đó bạn cung cấp khoá API của mình) và callback (trong đó bạn chỉ định tên của một 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ề 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 cách sử dụng tham số callback.

Thư viện

Khi tải API JavaScript cho Maps thông qua URL này, bạn có thể tuỳ ý tải thư viện bổ sung bằng cách 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 của Maps chính nhưng 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 API JavaScript của Maps.

Bản đồ 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 dành riêng 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%". Kích thước 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 phải đ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, 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 đồ: 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 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 bản đồ toàn bộ Trái đất dưới dạng một hình ảnh duy nhất sẽ yêu cầu 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à API JavaScript của Maps đượ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 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 JavaScript của Maps tải ô dựa trên mức thu phóng hiện tại, hãy xem hướng dẫn về bản đồ 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 bản đồ 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 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 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 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 một đố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 Mô tả
Map(mapDiv:Node, opts?:MapOptions ) Tạo bản đồ mới bên trong vùng chứa HTML nhất định — 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 nhất định, bản đồ bị làm tối hoặc 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". Hành vi này thường cho biết các vấn đề với khoá API hoặc việc thanh toán. Để sử dụng các sản phẩm 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 bao gồm một khóa 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 trong video này.

  • Tìm lỗi chính tả. Hãy nhớ rằng JavaScript là một ngôn ngữ phân biệt chữ hoa chữ thường.
  • Kiểm tra những vấn đề cơ bản – một số vấn đề phổ biến nhất xảy ra khi tạo bản đồ ban đầu. Chẳng hạn như:
    • Hãy 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 đồ.
    • Đảm bảo rằng bạn đã khai báo một 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 nên sẽ không hiển thị.
    Hãy tham khảo các ví dụ của chúng tôi để biết cách triển khai 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. 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 câu hỏi hay trên trang Hỗ trợ.