Tải Maps JavaScript API (original) (raw)

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

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:

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:

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

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

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

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ải tập lệnh, 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.

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, trong khi một số 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ố đượ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 Maps JavaScript:

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

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

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

Sử dụng các tham số này để yêu cầu một phiên bản cụ thể của API Maps JavaScript, 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 liên kết giới thiệu HTTP

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

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:

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

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

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 hoạt độ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.

Trước

Sau

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

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