Thêm Google Maps có Điểm đánh dấu bằng JavaScript

Giới thiệu

Hướng dẫn này cho bạn biết cách thêm bản đồ Google có điểm đánh dấu vào trang web bằng HTML, CSS và JavaScript. Bài viết này cũng hướng dẫn bạn cách đặt các tuỳ chọn bản đồ và cách sử dụng tính năng chèn thành phần điều khiển để thêm nhãn vào bản đồ.

Dưới đây là bản đồ mà bạn sẽ tạo bằng cách làm theo hướng dẫn này. Điểm đánh dấu được đặt tại Uluru (còn gọi là Ayers Rock) trong Vườn quốc gia Uluru-Kata Tjuta.

Bắt đầu

Có ba bước để tạo bản đồ Google có điểm đánh dấu trên trang web của bạn:

1. Lấy khoá API
2. Tạo trang HTML
3. Thêm bản đồ có điểm đánh dấu

Bạn cần có một trình duyệt web. Chọn một trình duyệt phổ biến như Google Chrome (nên dùng), Firefox, Safari hoặc Edge, dựa trên nền tảng của bạn trong danh sách trình duyệt được hỗ trợ.

Bước 1: Lấy khoá API

Phần này giải thích cách xác thực ứng dụng của bạn với Maps JavaScript API bằng khoá API của riêng bạn.

Hãy làm theo các bước sau để lấy khoá API:

1. Chuyển đến Google Cloud Console.

2. Tạo hoặc chọn một dự án.

3. Nhấp vào Tiếp tục để bật API và mọi dịch vụ liên quan.

4. Trên trang Thông tin xác thực, hãy lấy khoá API (và đặt các quy tắc hạn chế đối với khoá API). Lưu ý: Nếu có khoá API không bị hạn chế hoặc khoá có các quy tắc hạn chế đối với trình duyệt, thì bạn có thể sử dụng khoá đó.

5. Để ngăn chặn hành vi đánh cắp hạn mức và bảo mật khoá API, hãy xem bài viết Sử dụng khoá API.

6. Bật tính năng thanh toán. Hãy xem phần Mức sử dụng và thanh toán để biết thêm thông tin.

7. Sau khi bạn có khoá API, hãy thêm khoá đó vào đoạn mã sau bằng cách nhấp vào "YOUR_API_KEY". Sao chép và dán thẻ tập lệnh trình tải khởi động để sử dụng trên trang web của riêng bạn.

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

Bước 2: Tạo trang HTML

Sau đây là mã cho một trang web HTML cơ bản:

<!DOCTYPE html>
<!--
 @license
 Copyright 2025 Google LLC. All Rights Reserved.
 SPDX-License-Identifier: Apache-2.0
-->

<html>
  <head>
    <title>Add a Map</title>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
    <!-- 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: "YOUR_API_KEY", v: "weekly"});</script>
  </head>
  <body>

    <!-- The map, centered at Uluru, Australia. -->
    <gmp-map center="-25.344,131.031" zoom="4" map-id="DEMO_MAP_ID">
    </gmp-map>

  </body>
</html>

Đây là một trang HTML rất cơ bản, sử dụng phần tử gmp-map để hiển thị bản đồ trên trang. Bản đồ sẽ trống vì chúng ta chưa thêm mã JavaScript nào.

Tìm hiểu mã

Ở giai đoạn này trong ví dụ, chúng ta có:

• Khai báo ứng dụng là HTML5 bằng cách sử dụng nội dung khai báo !DOCTYPE html.
• Đã tải API JavaScript của Maps bằng trình nạp khởi động.
• Tạo một phần tử gmp-map để giữ bản đồ.

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

Bạn nên khai báo DOCTYPE là true trong ứng dụng web của mình. 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 DOCTYPE HTML5 như minh hoạ 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ế độ chuẩn", tức là ứng dụng của bạn phải tuân thủ nhiều trình duyệt hơn. DOCTYPE cũng được thiết kế để giảm dần một cách linh hoạt; những trình duyệt không hiểu sẽ bỏ qua và sử dụng "chế độ tương thích ngược" để hiển thị nội dung.

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

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

Tải Maps JavaScript API

Trình nạp khởi động chuẩn bị Maps JavaScript API để tải (không có thư viện nào được tải cho đến khi importLibrary() được gọi).

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

Xem Bước 3: Lấy khoá API để biết hướng dẫn về cách lấy khoá API của riêng bạn.

Ở giai đoạn này của hướng dẫn, một cửa sổ trống sẽ xuất hiện, chỉ hiển thị văn bản nhãn chưa được định dạng. Điều này là do chúng ta chưa thêm mã JavaScript nào.

Tạo một phần tử gmp-map

Để bản đồ hiển thị trên trang web, chúng ta phải dành 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ử gmp-map và lấy tệp đối chiếu cho phần tử này trong mô hình đối tượng tài liệu (DOM) của trình duyệt. Bạn cũng có thể sử dụng phần tử div để làm việc này (tìm hiểu thêm), nhưng bạn nên sử dụng phần tử gmp-map.

Đoạn mã dưới đây xác định phần tử gmp-map và đặt các tham số center, zoom và map-id.

<gmp-map center="-25.344,131.031" zoom="4" map-id="DEMO_MAP_ID">
</gmp-map>

Bạn luôn phải chọn center và zoom. Trong đoạn mã trên, thuộc tính center cho API biết vị trí đặt tâm của bản đồ và thuộc tính zoom chỉ định mức thu phóng cho bản đồ. Thu phóng: 0 là mức thu phóng thấp nhất và hiển thị toàn bộ Trái Đất. Đặt giá trị thu phóng cao hơn để phóng to Trái Đất ở độ phân giải cao hơn.

Mức thu phóng

Để cung cấp bản đồ của toàn bộ Trái Đất dưới dạng một hình ảnh duy nhất, bạn cần có một bản đồ khổng lồ hoặc một bản đồ nhỏ có độ phân giải thấp. Do đó, hình ảnh bản đồ trong Google Maps và API JavaScript của Maps được chia thành "mảnh" bản đồ và "mức thu phóng". Ở mức thu phóng thấp, một nhóm 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 ô 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 biết 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: Đất liền hoặc 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.

Đoạn mã dưới đây mô tả CSS đặt kích thước của phần tử gmp-map.

/* Set the size of the gmp-map element that contains the map */
gmp-map {
    height: 400px; /* The height is 400 pixels */
    width: 100%; /* The width is the width of the web page */
}

Trong đoạn mã trên, phần tử style đặt kích thước của gmp-map. Đặt chiều rộng và chiều cao lớn hơn 0px để bản đồ hiển thị. Trong trường hợp này, gmp-map được đặt thành chiều cao 400 pixel và chiều rộng 100% để hiển thị trên toàn bộ chiều rộng của trang web. Bạn nên luôn đặt rõ ràng kiểu chiều cao và chiều rộng.

Lưu ý: Đối với bản đồ raster, giới hạn cho kích thước tối đa là 6144 x 6144 pixel.

Bố trí thành phần điều khiển

Bạn có thể sử dụng tính năng chèn thành phần điều khiển để thêm các thành phần điều khiển biểu mẫu HTML vào bản đồ. Vị trí là một vị trí được xác định trước trên bản đồ; hãy sử dụng thuộc tính slot để đặt vị trí cần thiết cho một phần tử và lồng các phần tử trong phần tử gmp-map. Đoạn mã sau đây cho thấy cách thêm nhãn HTML vào góc trên bên trái của bản đồ.

<!-- The map, centered at Uluru, Australia. -->
<gmp-map center="-25.344,131.031" zoom="4" map-id="DEMO_MAP_ID">
  <div id="controls" slot="control-inline-start-block-start">
    <h3>My Google Maps Demo</h3>
  </div>
</gmp-map>

Bước 3: Thêm mã JavaScript

Phần này hướng dẫn bạn cách tải API JavaScript của Maps vào một trang web và cách viết JavaScript của riêng bạn bằng cách sử dụng API để thêm bản đồ có điểm đánh dấu trên đó.

TypeScript

async function init(): Promise<void> {
    // Request the needed libraries.
    const [{ AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary('marker'),
        google.maps.importLibrary('maps'),
    ]);
    // Get the gmp-map element.
    const mapElement = document.querySelector('gmp-map')!;

    // Get the inner map.
    const innerMap = mapElement.innerMap;

    // Set map options.
    innerMap.setOptions({
        mapTypeControl: false,
    });

    // Add a marker positioned at the map center (Uluru).
    new AdvancedMarkerElement({
        map: innerMap,
        position: mapElement.center,
        title: 'Uluru/Ayers Rock',
    });
}
void init();
index.ts

Lưu ý: Đọc hướng dẫn về cách sử dụng TypeScript và Google Maps.

JavaScript

async function init() {
    // Request the needed libraries.
    const [{ AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary('marker'),
        google.maps.importLibrary('maps'),
    ]);
    // Get the gmp-map element.
    const mapElement = document.querySelector('gmp-map');

    // Get the inner map.
    const innerMap = mapElement.innerMap;

    // Set map options.
    innerMap.setOptions({
        mapTypeControl: false,
    });

    // Add a marker positioned at the map center (Uluru).
    new AdvancedMarkerElement({
        map: innerMap,
        position: mapElement.center,
        title: 'Uluru/Ayers Rock',
    });
}
void init();
index.js

Mã trên thực hiện những việc sau khi initMap() được gọi:

• Tải thư viện maps và marker.
• Lấy phần tử bản đồ từ DOM.
• Đặt tuỳ chọn bản đồ bổ sung trên bản đồ bên trong.
• Thêm điểm đánh dấu vào bản đồ.

Lấy đối tượng bản đồ và đặt các tuỳ chọn

innerMap đại diện cho một thực thể của lớp Bản đồ. Để đặt các tuỳ chọn bản đồ, hãy lấy thực thể innerMap từ phần tử bản đồ rồi gọi setOptions. Đoạn mã sau đây cho thấy cách lấy thực thể innerMap từ DOM, sau đó gọi setOptions:

// Get the gmp-map element.
const mapElement = document.querySelector(
  "gmp-map"
) as google.maps.MapElement;

// Get the inner map.
const innerMap = mapElement.innerMap;

// Set map options.
innerMap.setOptions({
  mapTypeControl: false,
});

Chờ bản đồ tải xong

Khi sử dụng phần tử gmp-map, bản đồ sẽ tải không đồng bộ. Điều này có thể dẫn đến tình huống tương tranh nếu các yêu cầu khác được thực hiện tại thời điểm khởi chạy (ví dụ: yêu cầu về vị trí địa lý hoặc Chi tiết địa điểm). Để đảm bảo rằng mã của bạn chỉ chạy sau khi bản đồ được tải đầy đủ, hãy sử dụng trình xử lý sự kiện rảnh addListenerOnce trong hàm khởi chạy, như minh hoạ dưới đây:

// Do things once the map has loaded.
google.maps.event.addListenerOnce(innerMap, 'idle', () => {
    // Run this code only after the map has loaded.
    console.log("The map is now ready!");
});

Việc này đảm bảo rằng mã của bạn chỉ chạy sau khi bản đồ đã tải; trình xử lý chỉ được kích hoạt một lần trong vòng đời của ứng dụng.

Lưu ý về việc tối ưu hoá hiệu suất nội bộ:

Để cải thiện tốc độ tải trang, Maps JavaScript API có thể trì hoãn việc tải nội dung tương tác trong nội bộ cho đến khi phần tử hoặc vùng chứa tiếp cận khung nhìn. Những hoạt động tối ưu hoá nội bộ này có thể thay đổi bất cứ lúc nào mà không cần thông báo. Các phương thức này được thiết kế để nâng cao hiệu suất và không nên được dùng làm cơ chế quản lý việc thanh toán. Để đảm bảo không phát sinh phí thanh toán cho đến khi một phần tử xuất hiện, hãy trì hoãn việc tạo phần tử đó trong mã xử lý ứng dụng.

Mã ví dụ hoàn chỉnh

Xem mã ví dụ hoàn chỉnh tại đây:

TypeScript

async function init(): Promise<void> {
    // Request the needed libraries.
    const [{ AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary('marker'),
        google.maps.importLibrary('maps'),
    ]);
    // Get the gmp-map element.
    const mapElement = document.querySelector('gmp-map')!;

    // Get the inner map.
    const innerMap = mapElement.innerMap;

    // Set map options.
    innerMap.setOptions({
        mapTypeControl: false,
    });

    // Add a marker positioned at the map center (Uluru).
    new AdvancedMarkerElement({
        map: innerMap,
        position: mapElement.center,
        title: 'Uluru/Ayers Rock',
    });
}
void init();
index.ts

Lưu ý: Đọc hướng dẫn về cách sử dụng TypeScript và Google Maps.

JavaScript

async function init() {
    // Request the needed libraries.
    const [{ AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary('marker'),
        google.maps.importLibrary('maps'),
    ]);
    // Get the gmp-map element.
    const mapElement = document.querySelector('gmp-map');

    // Get the inner map.
    const innerMap = mapElement.innerMap;

    // Set map options.
    innerMap.setOptions({
        mapTypeControl: false,
    });

    // Add a marker positioned at the map center (Uluru).
    new AdvancedMarkerElement({
        map: innerMap,
        position: mapElement.center,
        title: 'Uluru/Ayers Rock',
    });
}
void init();
index.js

CSS

/*
 * Always set the map height explicitly to define the size of the div element
 * that contains the map.
 */
gmp-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>Add a Map</title>

        <link rel="stylesheet" type="text/css" href="./style.css" />
        <script type="module" src="./index.js"></script>
        <script>
            // prettier-ignore
            (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: "GOOGLE_MAPS_API_KEY"
            });
        </script>
    </head>
    <body>
        <!-- The map, centered at Uluru, Australia. -->
        <gmp-map center="-25.344,131.031" zoom="4" map-id="DEMO_MAP_ID">
            <div id="controls" slot="control-inline-start-block-start">
                <h3>My Google Maps Demo</h3>
            </div>
        </gmp-map>
    </body>
</html>
index.html

Tìm hiểu thêm về điểm đánh dấu:

• Giúp người dùng dễ tiếp cận điểm đánh dấu
• Điểm đánh dấu có biểu tượng đồ hoạ
• Ảnh động của điểm đánh dấu

Mẹo và cách khắc phục sự cố

• Tìm hiểu thêm về cách lấy toạ độ vĩ độ/kinh độ hoặc chuyển đổi địa chỉ thành toạ độ địa lý.
• Bạn có thể điều chỉnh các lựa chọn như kiểu và thuộc tính để tuỳ chỉnh bản đồ. Để biết thêm thông tin về cách tuỳ chỉnh bản đồ, hãy đọc hướng dẫn về tạo kiểu và vẽ trên bản đồ.
• Sử dụng Bảng điều khiển Công cụ cho nhà phát triển trong trình duyệt web để kiểm thử và chạy mã, đọc báo cáo lỗi và giải quyết vấn đề về mã.
• Sử dụng các phím tắt sau để mở bảng điều khiển trong Chrome:
  Command+Option+J (trên máy Mac) hoặc Control+Shift+J (trên Windows).

• Hãy làm theo các bước bên dưới để lấy toạ độ vĩ độ và kinh độ của một vị trí trên Google Maps.

  1. Mở Google Maps trong trình duyệt.
  2. Nhấp chuột phải vào vị trí chính xác trên bản đồ mà bạn cần toạ độ.
  3. Chọn toạ độ vĩ độ và kinh độ trong trình đơn.

• Bạn có thể chuyển đổi địa chỉ thành toạ độ vĩ độ và kinh độ bằng cách sử dụng dịch vụ Mã hoá địa lý. Hướng dẫn cho nhà phát triển cung cấp thông tin chi tiết về cách bắt đầu sử dụng dịch vụ Mã hoá địa lý.