Tải API JavaScript của Maps

Hướng dẫn này cho bạn biết cách tải API JavaScript cho Maps. 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
• Sử dụng thẻ tải tập lệnh trực tiếp
• Sử dụng gói trình tải js-api bức ảnh của Khắc phục vấn đề

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

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

Nếu bạn đã thêm một tệp ánh xạ bằng phần tử gmp-map, thì hàm initMap() của bạn 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:

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

initMap();

Ngoài ra, bạn có thể tải thư viện trực tiếp trong HTML như minh hoạ dưới đâ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 khoá API hợp lệ.

Thông số tùy chọn

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

• libraries: Danh sách thư viện API Maps JavaScript bổ sung được phân tách bằng dấu phẩy cần tải. Thường thì bạn không nên chỉ định một nhóm thư viện cố định, nhưng có thể sử dụng cho các 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 chế độ điều khiển, thông báo bản quyền, chỉ đường lái xe và nhãn kiểm soát, cũng như 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ã khu vực 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 lãnh thổ nhất định.

• authReferrerPolicy: Khách hàng Maps JS có thể định cấu hình các quy tắc hạn chế đối với đường 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, các hạn chế này có thể được định cấu hình để 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 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 tham số này được chỉ định và Các quy định hạn chế về đường liên kết giới thiệu HTTP được bật trên Cloud Console, thì API JavaScript của Maps sẽ chỉ có thể tải nếu có Hạn chế về đường 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 nào được chỉ định.

• mapIds: Một mảng mã nhận dạng ánh xạ. Yêu cầu tải trước cấu hình cho các mã bản đồ được chỉ định.

• channel: Xem phần 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 một cách nhanh chóng. Để theo dõi việc sử dụng các mã mẫu phức tạp hơn và cải thiện chất lượng giải pháp, Google sẽ đư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 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. Tuy nhiên, hãy cẩn thận để chỉ đưa URL đó vào một lần cho mỗi lượt tải trang.

Thêm thẻ tập lệnh

Để tải Maps JavaScript API cùng dòng trong một tệp HTML, hãy thêm một 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 API JavaScript của Maps. Một số thông số là bắt buộc trong khi các thông số khác 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 ví dụ sau đây 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 ví dụ 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>

Các tham số bắt buộc (trực tiếp)

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

• 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ố không bắt buộc (trực tiếp)

Hãy sử dụng những tham số này để yêu cầu một phiên bản cụ thể của Maps JavaScript API, tải thêm thư viện, bản địa hoá bản đồ hoặc chỉ định chính sách kiểm tra đường 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 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 hành động khi API JavaScript của Maps có sẵn.) Được cung cấp kể từ phiên bản 3.55.

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

• v: Phiên bản của API Maps JavaScript nên sử dụng.

• libraries: Danh sách thư viện API Maps JavaScript bổ sung được phân tách bằng dấu phẩy cần tải.

• language: Ngôn ngữ sử dụng. Điều này ảnh hưởng đến tên của chế độ điều khiển, thông báo bản quyền, chỉ đường lái xe và nhãn điều khiển, cũng như 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ã khu vực 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 lãnh thổ nhất định.

• auth_referrer_policy: Khách hàng có thể định cấu hình Các quy định hạn chế về đường 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, các hạn chế này có thể được định cấu hình để 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ừ API JavaScript của Maps. Tính năng này chỉ có trong phiên bản 3.46. Khi tham số này được chỉ định và Các quy định hạn chế về đường liên kết giới thiệu HTTP được bật trên Cloud Console, thì API JavaScript của Maps sẽ chỉ có thể tải nếu có Quy định hạn chế về đường 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 chỉ định đường dẫn.

• mapIds: Danh sách mã bản đồ được phân tách bằng dấu phẩy. Yêu cầu tải trước cấu hình cho các mã bản đồ được chỉ định.

• channel: Xem phần 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 một cách nhanh chóng. Để theo dõi việc sử dụng các mã mẫu phức tạp hơn và cải thiện chất lượng giải pháp, Google sẽ đư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 là dành cho Google. Hãy xem thông số về các giải pháp của Nền tảng Google Maps để biết thêm thông tin.

Sử dụng gói trình tải js-api của Phim

Gói @googlemaps/js-api-loader có sẵn, để tải qua trình quản lý gói NP. Hãy cài đặt ứng dụng đó 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 cho thấy giao diện Promise (Lời hứa) và giao diện callback. Sau đây là ví dụ 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 cho thấy việc 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
});

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 quá trình 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&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ã xử lý ứng dụng của bạn:

• Thay đổi hàm initMap() của bạn 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();