Thông báo: Kiểu bản đồ cơ sở mới sắp ra mắt trên Nền tảng Google Maps. Bản cập nhật này về kiểu bản đồ bao gồm bảng màu mặc định mới, ghim hiện đại và các điểm cải tiến về trải nghiệm và khả năng sử dụng bản đồ. Tất cả kiểu bản đồ sẽ được tự động cập nhật vào tháng 3 năm 2025. Để biết thêm thông tin về phạm vi cung cấp và cách chọn sử dụng sớm hơn, hãy xem bài viết Kiểu bản đồ mới cho Nền tảng Google Maps.

Trang này được dịch bởi Cloud Translation API.

Tải API JavaScript của Maps

Hướng dẫn này cho bạn biết cách tải API Maps JavaScript. Có ba cách để thực hiện việc này:

Sử dụng tính năng nhập thư viện động
Sử dụng thẻ tải tập lệnh trực tiếp
Sử dụng gói js-api-loader của NPM

Sử dụng tính năng Nhập thư viện động

Tính năng nhập thư viện động cung cấp khả năng tải thư viện trong thời gian chạy. Điều này cho phép bạn yêu cầu các thư viện cần thiết tại thời điểm bạn cần, thay vì tất cả cùng một lúc tại thời điểm tải. Phương thức này cũng giúp trang của bạn không tải nhiều lần API Maps JavaScript.

Tải API Maps JavaScript bằng cách thêm trình tải bootstrap cùng dòng vào mã ứng dụng, như 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>

Bạn cũng có thể thêm mã trình tải khởi động trực tiếp vào mã JavaScript.

Để 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 async. Việc khai báo biến cho các lớp cần thiết cho phép bạn bỏ qua việc sử dụng đường dẫn đủ điều kiện (ví dụ: google.maps.Map), như trong ví dụ mã sau:

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

Hàm của bạn cũng có thể tải thư viện mà không cần khai báo biến cho các lớp cần thiết. Điều này đặc biệt hữu ích nếu bạn đã thêm bản đồ bằng phần tử gmp-map:

async function initMap() {
  google.maps.importLibrary("maps");
  google.maps.importLibrary("marker");
}

initMap();

Ngoài ra, bạn có thể tải trực tiếp các thư viện trong HTML như minh hoạ dưới đây:

<script>
google.maps.importLibrary("maps");
google.maps.importLibrary("marker");
</script>

Tìm hiểu cách chuyển sang API Tải thư viện động.

Thông số bắt buộc

key: Khoá API của bạn. API JavaScript của Maps sẽ không tải trừ khi bạn chỉ định một khoá API hợp lệ.

Thông số tùy chọn

v: Phiên bản của Maps JavaScript API cần tải.
libraries: Danh sách được phân tách bằng dấu phẩy gồm các thư viện Maps JavaScript API bổ sung cần tải. Bạn không nên chỉ định một nhóm thư viện cố định, nhưng có thể sử dụng nhóm thư viện này cho những nhà phát triển muốn điều chỉnh hành vi lưu vào bộ nhớ đệm trên trang web của họ.
language: Ngôn ngữ cần sử dụng. Điều này ảnh hưởng đến tên của các nút điều khiển, thông báo bản quyền, chỉ đường và nhãn điều khiển, cũng như nội dung phản hồi yêu cầu dịch vụ. Xem danh sách ngôn ngữ được hỗ trợ.
region: Mã khu vực cần sử dụng. Thao tác này sẽ thay đổi hành vi của bản đồ dựa trên một quốc gia hoặc vùng lãnh thổ nhất định.
authReferrerPolicy: Khách hàng sử dụng Maps JS có thể định cấu hình các Hạn chế về liên kết giới thiệu HTTP trong Cloud Console để giới hạn những URL được phép sử dụng một Khoá API cụ thể. Theo mặc định, bạn có thể định cấu hình các quy tắc hạn chế này để chỉ cho phép một số đường dẫn nhất định sử dụng Khoá API. Nếu bất kỳ URL nào trên cùng một miền hoặc nguồn gốc đều có thể sử dụng Khoá API, thì bạn có thể đặt authReferrerPolicy: "origin" để giới hạn lượng dữ liệu được gửi khi uỷ quyền các yêu cầu từ API JavaScript của Maps. Khi bạn chỉ định tham số này và bật Hạn chế liên kết giới thiệu HTTP trên Cloud Console, API JavaScript của Maps sẽ chỉ có thể tải nếu có Hạn chế liên kết giới thiệu HTTP khớp với miền của trang web hiện tại mà không có đường dẫn được chỉ định.
mapIds: Một mảng mã bản đồ. Tải trước cấu hình cho các mã bản đồ đã chỉ định.
channel: Xem phần Theo dõi mức sử dụng theo kênh.
solutionChannel: Nền tảng Google Maps cung cấp nhiều loại mã mẫu để giúp bạn nhanh chóng bắt đầu và chạy. Để theo dõi việc sử dụng các mẫu mã phức tạp hơn và cải thiện chất lượng giải pháp, Google đưa tham số truy vấn solutionChannel vào các lệnh gọi API trong mã mẫu của chúng tôi.

Sử dụng thẻ tải tập lệnh trực tiếp

Phần này cho biết cách sử dụng thẻ tải tập lệnh trực tiếp. Vì tập lệnh trực tiếp tải thư viện khi bản đồ tải, nên tập lệnh này có thể đơn giản hoá các bản đồ được tạo bằng phần tử gmp-map bằng cách không cần yêu cầu rõ ràng các thư viện trong thời gian chạy. Vì thẻ tải tập lệnh trực tiếp tải tất cả thư viện được yêu cầu cùng một lúc khi tập lệnh được tải, nên hiệu suất có thể bị ảnh hưởng đối với một số ứng dụng. Chỉ đưa thẻ tải tập lệnh trực tiếp vào một lần mỗi khi tải trang.

Thêm thẻ tập lệnh

Để tải API JavaScript của Maps cùng dòng trong 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>

Tham số URL tải tập lệnh trực tiếp

Phần này thảo luận về tất cả các tham số mà bạn có thể chỉ định trong chuỗi truy vấn của URL tải tập lệnh khi tải API JavaScript của Maps. Một số tham số là bắt buộc, còn lại là không bắt buộc. Theo tiêu chuẩn trong URL, tất cả các tham số được phân tách bằng ký tự dấu và (&).

URL mẫu sau đây có phần giữ chỗ cho tất cả tham số có thể có:

https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY
&loading=async
&callback=FUNCTION_NAME
&v=VERSION
&libraries="LIBRARIES"
&language="LANGUAGE"
&region="REGION"
&auth_referrer_policy="AUTH_REFERRER_POLICY"
&map_ids="MAP_IDS"
&channel="CHANNEL"
&solution_channel="SOLUTION_IDENTIFIER"

URL trong thẻ script mẫu sau đây sẽ tải API JavaScript của Maps:

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

Tham số bắt buộc (trực tiếp)

Bạn cần có các tham số sau khi tải API Maps JavaScript.

key: Khoá API của bạn. API JavaScript của Maps sẽ không tải trừ phi bạn chỉ định một khoá API hợp lệ.

Tham số tuỳ chọn (trực tiếp)

Sử dụng các thông số này để yêu cầu một phiên bản cụ thể của API JavaScript của Maps, tải các thư viện bổ sung, bản địa hoá bản đồ của bạn hoặc chỉ định chính sách kiểm tra liên kết giới thiệu HTTP

loading: Chiến lược tải mã mà Maps JavaScript API có thể sử dụng. Đặt thành async để cho biết API JavaScript của Maps chưa được tải đồng bộ và không có mã JavaScript nào được sự kiện load của tập lệnh kích hoạt. Bạn nên đặt giá trị này thành async bất cứ khi nào có thể để cải thiện hiệu suất. (Thay vào đó, hãy sử dụng thông số callback để thực hiện các thao tác khi có API JavaScript của Maps.) Có sẵn từ phiên bản 3.55.
callback: Tên của một hàm toàn cục sẽ được gọi sau khi API Maps JavaScript tải xong.
v: Phiên bản của API Maps JavaScript cần sử dụng.
libraries: Danh sách được phân tách bằng dấu phẩy gồm các thư viện Maps JavaScript API bổ sung cần tải.
language: Ngôn ngữ cần sử dụng. Điều này ảnh hưởng đến tên của các nút điều khiển, thông báo bản quyền, chỉ đường và nhãn điều khiển, cũng như câu trả lời cho các yêu cầu dịch vụ. Xem danh sách ngôn ngữ được hỗ trợ.
region: Mã khu vực cần sử dụng. Thao tác này sẽ thay đổi hành vi của bản đồ dựa trên một quốc gia hoặc vùng lãnh thổ nhất định.
auth_referrer_policy: Khách hàng có thể định cấu hình các quy tắc Hạn chế liên kết giới thiệu HTTP trong Cloud Console để giới hạn những URL được phép sử dụng một Khoá API cụ thể. Theo mặc định, bạn có thể định cấu hình các quy tắc hạn chế này để chỉ cho phép một số đường dẫn nhất định sử dụng Khoá API. Nếu bất kỳ URL nào trên cùng một miền hoặc nguồn gốc đều có thể sử dụng Khoá API, thì bạn có thể đặt auth_referrer_policy=origin để giới hạn lượng dữ liệu được gửi khi uỷ quyền các yêu cầu từ API JavaScript của Maps. Tính năng này có trong phiên bản 3.46 trở lên. Khi bạn chỉ định tham số này và bật Hạn chế giới thiệu HTTP trên Bảng điều khiển đám mây, API JavaScript của Maps sẽ chỉ có thể tải nếu có Hạn chế giới thiệu HTTP khớp với miền của trang web hiện tại mà không có đường dẫn được chỉ định.
mapIds: Danh sách mã bản đồ được phân tách bằng dấu phẩy. Tải trước cấu hình cho các mã bản đồ đã chỉ định.
channel: Xem phần Theo dõi mức sử dụng theo kênh.
solution_channel: Nền tảng Google Maps cung cấp nhiều loại mã mẫu để giúp bạn nhanh chóng bắt đầu và chạy. Để theo dõi việc sử dụng các mẫu mã phức tạp hơn và cải thiện chất lượng giải pháp, Google đưa tham số truy vấn solution_channel vào các lệnh gọi API trong mã mẫu của chúng tôi.

Lưu ý: Tham số truy vấn này chỉ dành cho Google sử dụng. Hãy xem thông số giải pháp trên Nền tảng Google Maps để biết thêm thông tin.

Sử dụng gói js-api-loader của NPM

Gói @googlemaps/js-api-loader có sẵn để tải qua trình quản lý gói NPM. Cài đặt 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 hiển thị một 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

Xem một mẫu có js-api-loader.

Ví dụ sau đây cho thấy cách sử dụng loader.importLibrary() để tải thư viện:

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

loader
  .importLibrary('maps')
  .then(({Map}) => {
    new Map(document.getElementById("map"), mapOptions);
  })
  .catch((e) => {
    // do something
});

Di chuyển sang API Nhập thư viện động

Phần này trình bày các bước cần thiết để di chuyển tính năng tích hợp của bạn nhằm sử dụng API Nhập thư viện động.

Các bước di chuyển

Trước tiên, hãy thay thế thẻ tải tập lệnh trực tiếp bằng thẻ trình tải khởi động cùng dòng.

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

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

Tiếp theo, hãy cập nhật mã ứng dụng:

Thay đổi hàm initMap() thành không đồng bộ.
Gọi importLibrary() để tải và truy cập vào các thư viện bạn cần.

let map;

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

window.initMap = initMap;

let map;
// initMap is now async
async function initMap() {
    // Request libraries when needed, not in the script tag.
    const { Map } = await google.maps.importLibrary("maps");
    // Short namespaces can be used.
    map = new Map(document.getElementById("map"), {
        center: { lat: -34.397, lng: 150.644 },
        zoom: 8,
    });
}

initMap();

Tải API JavaScript của Maps

Sử dụng tính năng Nhập thư viện động

TypeScript

JavaScript

Thông số bắt buộc

Thông số tùy chọn

Sử dụng thẻ tải tập lệnh trực tiếp

Thêm thẻ tập lệnh

Tham số URL tải tập lệnh trực tiếp

Tham số bắt buộc (trực tiếp)

Tham số tuỳ chọn (trực tiếp)

Sử dụng gói js-api-loader của NPM

TypeScript

JavaScript

Di chuyển sang API Nhập thư viện động

Các bước di chuyển

Trước

Sau

Trước

Sau