Tải Maps JavaScript API

Hướng dẫn này cho bạn biết cách tải Maps JavaScript API. Có 3 cách để làm 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 NPM js-api-loader

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 khi tải. Thao tác này cũng giúp trang của bạn không tải Maps JavaScript API nhiều lần.

Tải Maps JavaScript API bằng cách thêm trình tải khởi động nội tuyến vào mã ứ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 mã trình tải khởi động trực tiếp vào mã JavaScript.

Để tải các thư viện trong thời gian chạy, hãy dùng toán tử await để gọi importLibrary() từ bên trong hàm async. Việc khai báo các 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ư minh hoạ trong ví dụ mã sau:

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 các 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 một bản đồ bằng phần tử gmp-map. Nếu không có biến này, bạn phải sử dụng các đường dẫn đủ điều kiện, ví dụ: google.maps.Map:

let map;
let center =  { lat: -34.397, lng: 150.644 };

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

  map = new google.maps.Map(document.getElementById("map"), {
    center,
    zoom: 8,
    mapId: "DEMO_MAP_ID",
  });

  addMarker();
}

async function addMarker() {
  const marker = new google.maps.marker.AdvancedMarkerElement({
    map,
    position: center,
  });
}

initMap();

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

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

Tìm hiểu cách di chuyển sang Dynamic Library Loading API.

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 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: Một mảng các thư viện Maps JavaScript API bổ sung cần tải. Việc chỉ định một nhóm thư viện cố định thường không được khuyến khích, nhưng vẫn 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ữ 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ỉ dẫn lái xe 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 API dựa trên một quốc gia hoặc lãnh thổ nhất định.

• authReferrerPolicy: Khách hàng Maps JS có thể định cấu hình Chế độ hạn chế của HTTP Referrer 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 có thể sử dụng Khoá API, 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ừ Maps JavaScript API. Khi tham số này được chỉ định và bạn bật chế độ Giới hạn HTTP Referrer trên Cloud Console, Maps JavaScript API sẽ chỉ có thể tải nếu có một Giới hạn HTTP Referrer 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ã nhận dạng bản đồ. Khiến cấu hình cho các mã nhận dạng bản đồ đã chỉ định được tải sẵn. Bạn không bắt buộc phải chỉ định mã bản đồ tại đây để sử dụng mã bản đồ, nhưng những nhà phát triển muốn tinh chỉnh hiệu suất mạng có thể sử dụng.

• channel: Xem phần Theo dõi mức sử dụng theo từng 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 sẽ thêm 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 các 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 loại bỏ nhu cầu 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ả cá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ỉ thêm thẻ tải tập lệnh trực tiếp một lần cho mỗi lần tải trang.

Lưu ý: Bạn có thể gọi importLibrary sau khi thẻ tải tập lệnh trực tiếp đã tải xong.

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

URL ví dụ sau đây có cá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 của ví dụ sau đây sẽ tải Maps JavaScript API:

<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 phải có các tham số sau đây 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 bạn chỉ định một khoá API hợp lệ.

Tham số không bắt buộc (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 Maps JavaScript API, tải các thư viện bổ sung, bản địa hoá bản đồ hoặc chỉ định chính sách kiểm tra giá trị 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 kích hoạt bởi sự kiện load của tập lệnh. Bạn nên đặt chế độ 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 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 chung sẽ được gọi sau khi Maps JavaScript API tải hoàn toàn.

• v: Phiên bản của Maps JavaScript API sẽ được dùng.

• libraries: Danh sách các thư viện Maps JavaScript API bổ sung được phân tách bằng dấu phẩy để 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 chế độ điều khiển, thông báo bản quyền, chỉ dẫn lái xe và nhãn điều khiển, cũng như các câu trả lời cho 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 API dựa trên một quốc gia hoặc lãnh thổ nhất định.

• auth_referrer_policy: Khách hàng có thể định cấu hình Chế độ hạn chế đối với giá trị 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 có thể sử dụng Khoá API, 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ừ Maps JavaScript API. 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 Chế độ hạn chế của HTTP Referrer trên Cloud Console, Maps JavaScript API sẽ chỉ có thể tải nếu có một Chế độ hạn chế của HTTP Referrer 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 đồ được chỉ định được tải sẵn. Bạn không bắt buộc phải chỉ định mã bản đồ tại đây để sử dụng mã bản đồ, nhưng những nhà phát triển muốn điều chỉnh hiệu suất mạng một cách tỉ mỉ có thể sử dụng.

• channel: Xem phần Theo dõi mức sử dụng theo từng 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 sẽ thêm 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 ý: Google sử dụng tham số truy vấn này. Hãy xem tham số giải pháp của Nền tảng Google Maps để biết thêm thông tin.

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

Gói @googlemaps/js-api-loader có sẵn để tải bằng 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 cách:

import { Loader } from "@googlemaps/js-api-loader"

Trình tải này hiển thị một Giao diện lệnh gọi lại và Lời hứa. 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

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ẫu có js-api-loader.

Ví dụ sau đây minh hoạ cách sử dụng loader.importLibrary() để tải các 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 Dynamic Library Import API

Phần này trình bày các bước cần thiết để di chuyển chế độ tích hợp của bạn sang sử dụng Dynamic Library Import API.

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 nội tuyến.

Trước

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&libraries=maps&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ã ứ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();