Tải API JavaScript của Maps

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

• Sử dụng tính năng Nhập thư viện động (Khuyên dùng)
• Sử dụng gói mới js-api-loader
• Sử dụng thẻ tải tập lệnh trực tiếp

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

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>

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

Để 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, như trong mã ví dụ 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

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

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

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ừ phi khoá API hợp lệ được chỉ định.

Thông số tùy chọn

• v: Phiên bản của Maps JavaScript API sẽ tải.

• libraries: Danh sách được phân tách bằng dấu phẩy gồm các thư viện API JavaScript bổ sung của Maps cần tải. Thường thì bạn không nên chỉ định một tập hợp thư viện cố định, nhưng tính năng này có sẵn cho những nhà phát triển muốn tinh chỉnh hành vi lưu vào bộ nhớ đệm trên trang web của họ.

• language: Ngôn ngữ 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, thông tin chỉ đường lái xe và nhãn kiểm soát cũng như phản hồi cho các yêu cầu dịch vụ. Xem danh sách ngôn ngữ được hỗ trợ.

• region: Mã region cần sử dụng. Điều này làm 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 của Maps JS 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 Khoá API cụ thể. Theo mặc định, bạn có thể định cấu hình cá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 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 cho các yêu cầu từ API JavaScript của Maps. Khi tham số này được chỉ định và Hạn chế liên kết giới thiệu HTTP được bật 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 đồ. Khiến cấu hình cho các mã bản đồ đã chỉ định được tải trước.

• channel: Xem Theo dõi mức sử dụng mỗi kênh.

• solutionChannel: Nền tảng Google Maps cung cấp nhiều loại mã mẫu để giúp bạn thiết lập và sử dụng nhanh chóng. Để theo dõi tình hình sử dụng mã mẫu 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 mình.

Sử dụng gói gradle js-api-loader

Có sẵn gói @googlemaps/js-api-loader để tải qua trình quản lý gói ALIAS. Hãy cài đặt 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 Promise (Lời hứa) và callback (gọi lại). Phần sau đây minh hoạ việc 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

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

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

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. Bạn nên di chuyển sang Dynamic Library Loading API (API Tải thư viện động).

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ạ dưới đây.

<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 thông 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 Maps JavaScript API. Một số tham số là bắt buộc, trong khi một số khác là không bắt buộc. Theo tiêu chuẩn trong URL, tất cả tham số được phân tách bằng ký tự ký hiệu và (&).

URL ví dụ sau có phần giữ chỗ cho tất cả cá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 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)

Các tham số sau là bắt buộc khi tải Maps JavaScript API.

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

• callback: Tên của một hàm toàn cục sẽ được gọi khi API JavaScript của Maps tải hoàn toàn.

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

Hãy sử dụng các tham số này để yêu cầu một phiên bản cụ thể của Maps JavaScript API, tải 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à API JavaScript của Maps có thể sử dụng. Đặt thành async để cho biết rằng 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 thuộc tính 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 tham số callback để thực hiện các hành động khi Maps JavaScript API có sẵn.) Bắt đầu từ phiên bản 3.55.

• callback: Tên của một hàm toàn cục sẽ được gọi khi API JavaScript của Maps tải hoàn toàn.

• v: Phiên bản của Maps JavaScript API sẽ 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 API JavaScript bổ sung của Maps cần tải.

• language: Ngôn ngữ 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, thông tin chỉ đường lái xe và nhãn kiểm soát, cũng như nội dung phản hồi các yêu cầu dịch vụ. Xem danh sách ngôn ngữ được hỗ trợ.

• region: Mã region cần sử dụng. Điều này làm 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 Khoá API cụ thể. Theo mặc định, bạn có thể định cấu hình cá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 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 cho các yêu cầu từ API JavaScript của Maps. Tính năng này bắt đầu có từ phiên bản 3.46. Khi tham số này được chỉ định và Hạn chế giới thiệu HTTP được bật trên Cloud Console, Maps JavaScript API sẽ chỉ có thể tải nếu có một 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: Danh sách mã bản đồ được phân tách bằng dấu phẩy. Khiến cấu hình cho các mã bản đồ đã chỉ định được tải trước.

• channel: Xem Theo dõi mức sử dụng mỗi kênh.

• solution_channel: Nền tảng Google Maps cung cấp nhiều loại mã mẫu để giúp bạn thiết lập và sử dụng nhanh chóng. Để theo dõi tình hình sử dụng mã mẫu 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 mình.

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

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

Phần này bao gồm các bước cần thiết để di chuyển nội dung tích hợp 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.

Trước

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

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>

Tiếp theo, hãy cập nhật mã xử lý ứng dụng của bạn:

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

Trước

let map;

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

window.initMap = initMap;

Sau

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