Hướng dẫn này cho bạn biết cách tải API JavaScript cho Maps. Có là 3 cách để thực hiện điều 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 khi cần, thay vì tất cả cùng một lúc tại thời điểm tải. Việc này cũng bảo vệ trang của bạn không tải API JavaScript cho Maps nhiều lần.
Tải API JavaScript cho Maps bằng cách thêm quy trình tự khởi động cùng dòng vào mã xử lý ứng dụng của bạn, như thể hiện 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 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 bằng cách sử dụng một đường dẫn đủ điều kiện (ví dụ: google.maps.Map
), như minh hoạ trong
ví dụ về 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();
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();
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, đặc biệt hữu ích nếu bạn đã thêm một bản đồ bằng cách sử dụ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 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 một khoá API hợp lệ.
Thông số tùy chọn
v
: Phiên bản của API JavaScript cho Maps để tải.libraries
: Danh sách API JavaScript bổ sung được phân tách bằng dấu phẩy thư viện cần tải. Chỉ định một nhóm thư viện cố định thường không được đề xuất, 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ủa sử dụng. Điều này ảnh hưởng đến tên của bảng điều khiển, thông báo bản quyền, chỉ đường lái xe, và kiểm soát nhã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
: Khu vực mã để 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ổ.authReferrerPolicy
: Khách hàng Maps JS có thể định cấu hình HTTP Referrer Các hạn chế 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ể thiết lập các hạn chế này để cho phép một số đường dẫn nhất định để sử dụng Khoá API. Nếu có 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ể đặtauthReferrerPolicy: "origin"
để giới hạn lượng dữ liệu được gửi khi cho phép các yêu cầu từ API JavaScript của Maps. Thời gian thông 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, Maps JavaScript API 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ã 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 để 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ô hình mã mẫu và cải thiện chất lượng giải pháp, Google bao gồm Tham số truy vấnsolutionChannel
trong lệnh gọi API trong mã mẫu của chúng ta.
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ởi vì người mua trực tiếp
khi tập lệnh tải thư viện, tập lệnh này có thể đơn giản hoá các bản đồ được tạo bằng cách sử dụ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 tại
thời gian chạy. Vì thẻ tải tập lệnh trực tiếp sẽ tải tất cả thư viện được yêu cầu tại
khi tập lệnh được tải, hiệu suất có thể bị ảnh hưởng đối với một số
. Chỉ bao gồm thẻ tải tập lệnh trực tiếp một lần cho mỗi lượt tải trang.
Thêm thẻ tập lệnh
Để tải Maps JavaScript API nội tuyến 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ả tham số mà bạn có thể chỉ định trong truy vấn
của URL tải tập lệnh khi tải API JavaScript cho 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. Như tiêu chuẩn trong
URL, tất 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"
®ion="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. Chiến lược phát hành đĩa đơn API JavaScript của Maps sẽ không tải trừ khi khoá API hợp lệ được đã chỉ định.
Thông số không bắt buộc (trực tiếp)
Sử dụng những thông số này để yêu cầu một phiên bản cụ thể của API Maps JavaScript, tải thư viện bổ sung, bản địa hoá bản đồ hoặc chỉ định việc kiểm tra đường liên kết giới thiệu HTTP chính sách
loading
: Chiến lược tải mã mà API JavaScript của Maps có thể sử dụng. Đặt thànhasync
để 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ệnload
của tập lệnh kích hoạt. Bạn nên đặt giá trị này thànhasync
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 hàm chung sẽ được gọi một lần API Maps JavaScript tải hoàn toàn.v
: Phiên bản của API JavaScript cho Maps để sử dụng.libraries
: Danh sách API JavaScript bổ sung được phân tách bằng dấu phẩy thư viện cần tải.language
: Ngôn ngữ của sử dụng. Điều này ảnh hưởng đến tên của bảng điều khiển, thông báo bản quyền, chỉ đường lái xe, và kiểm soát nhã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
: Khu vực mã để 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ổ.auth_referrer_policy
: Khách hàng có thể định cấu hình đường liên kết giới thiệu HTTP Các hạn chế 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ể thiết lập các hạn chế này để cho phép một số đường dẫn nhất định để sử dụng Khoá API. Nếu có 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ể đặtauth_referrer_policy=origin
để giới hạn lượng dữ liệu được gửi khi cho phép 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 thông số này được chỉ định và tính năng Hạn chế liên kết 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 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 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. 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 để 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ô hình mã mẫu và cải thiện chất lượng giải pháp, Google bao gồm Tham số truy vấnsolution_channel
trong lệnh gọi API trong mã mẫu của chúng ta.
Sử dụng gói trình tải js-api của Phim
Thẻ @googlemaps/js-api-loader gói có sẵn, để tải qua trình quản lý gói GMS. Cài đặt ứng dụng này bằng sau đây:
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ạ
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, }); });
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, }); });
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 cơ chế 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 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();