Tải Maps JavaScript API

Hướng dẫn này trình bày 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

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. Tính năng 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 trong thời gian tải. Tính năng này cũng giúp bảo vệ trang của bạn khỏi việc 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 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 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ừ 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ụ về mã sau:

let map;
async function initMap() {
    const { Map, RenderingType } = (await google.maps.importLibrary('maps'));
    map = new Map(document.getElementById('map'), {
        center: { lat: -34.397, lng: 150.644 },
        zoom: 8,
        renderingType: RenderingType.VECTOR,
    });
}
initMap();
index.js

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, bạn phải sử dụng đườ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 API Tải thư viện động.

Thông số bắt buộc

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

Thông số tuỳ 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 libraries để bắt đầu tải trước. Việc chỉ định một tập hợp thư viện cố định thường không được đề xuất, nhưng 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ọ. Bạn vẫn cần gọi google.maps.importLibrary() cho từng thư viện đã chọn trước khi sử dụng.

  • 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ỉ đường lái xe và nhãn nút điều khiển, cũng như các phản hồ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. Điều này làm 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 sử dụng Maps JS có thể định cấu hình các quy tắc hạn chế về 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 gốc đều 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 cho các yêu cầu từ Maps JavaScript API. Khi tham số này được chỉ định và các quy tắc hạn chế về HTTP Referrer được bật trên Cloud Console, Maps JavaScript API sẽ chỉ có thể tải nếu có một quy tắc hạn chế về 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ã bản đồ. Làm cho cấu hình cho các mã bản đồ được chỉ định được tải trước. Việc chỉ định mã bản đồ ở đây không bắt buộc đối với việc sử dụng mã bản đồ, nhưng có sẵn cho những nhà phát triển muốn tinh chỉnh hiệu suất mạng.

  • channel: Xem phần Theo dõi mức sử dụng theo kênh.

  • internalUsageAttributionIds: Một mảng mã nhận dạng phân bổ mức sử dụng giúp Google hiểu được những thư viện và mẫu nào hữu ích cho nhà phát triển, chẳng hạn như mức sử dụng thư viện phân cụm điểm đánh dấu. Để chọn không gửi mã nhận dạng phân bổ mức sử dụng, bạn có thể xoá thuộc tính này hoặc đặt giá trị thành một mảng trống ([]). Hệ thống sẽ chỉ gửi các giá trị duy nhất. Xem tham số giải pháp Google Maps Platform để biết thêm thông tin.

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 loại bỏ nhu cầu yêu cầu thư viện một cách rõ ràng 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ỉ đưa thẻ tải tập lệnh trực tiếp một lần cho mỗi lần tải trang.

Thêm thẻ tập lệnh

Để tải Maps JavaScript API cùng dòng trong tệp HTML, hãy thêm thẻ script như minh hoạ bên dưới.

<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 trình 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 Maps JavaScript API:

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

Thông số bắt buộc (trực tiếp) {:.hide-from-toc}

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

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

Thông số tuỳ chọn (trực tiếp) {:.hide-from-toc}

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êm thư viện, bản địa hoá bản đồ hoặc chỉ định chính sách kiểm tra HTTP referrer

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

  • callback: Tên của một hàm toàn cục 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 cần sử dụng.

  • libraries: Danh sách các thư việnMaps 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 nút điều khiển, thông báo bản quyền, chỉ đường lái xe và nhãn nút điều khiển, cũng như các phản hồ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. Điều này làm 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 các quy tắc hạn chế về 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 gốc đều 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 cho các yêu cầu từ Maps JavaScript API. 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à các quy tắc hạn chế về HTTP Referrer được bật trên Cloud Console, Maps JavaScript API sẽ chỉ có thể tải nếu có một quy tắc hạn chế về 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.

  • map_ids: Danh sách mã bản đồ được phân tách bằng dấu phẩy. Làm cho cấu hình cho các mã bản đồ được chỉ định được tải trước. Việc chỉ định mã bản đồ ở đây không bắt buộc đối với việc sử dụng mã bản đồ, nhưng có sẵn cho những nhà phát triển muốn tinh chỉnh hiệu suất mạng.

  • channel: Xem phần Theo dõi mức sử dụng theo kênh.

  • internal_usage_attribution_ids: Danh sách mã nhận dạng phân bổ mức sử dụng được phân tách bằng dấu phẩy giúp Google hiểu được những thư viện và mẫu nào hữu ích cho nhà phát triển, chẳng hạn như mức sử dụng thư viện phân cụm điểm đánh dấu. Để chọn không gửi mã nhận dạng phân bổ mức sử dụng, bạn có thể xoá thuộc tính này hoặc thay thế giá trị bằng một chuỗi trống. Hệ thống sẽ chỉ gửi các giá trị duy nhất. Xem tham số giải pháp Google Maps Platform để 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 gói này bằng lệnh sau:

npm install @googlemaps/js-api-loader

Nhập gói như minh hoạ ở đây:

import { setOptions, importLibrary } from "@googlemaps/js-api-loader"

Trình tải sử dụng Promises để cung cấp thư viện. Tải thư viện bằng phương thức importLibrary(). Ví dụ sau đây cho biết cách sử dụng trình tải để tải bản đồ:

TypeScript

// Import the needed libraries.
import { setOptions, importLibrary } from '@googlemaps/js-api-loader';

const API_KEY = 'AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8';

async function initMap(): Promise<void> {
    // Set loader options.
    setOptions({
        key: API_KEY,
        v: 'weekly',
    });

    // Load the Maps library.
    const { Map } = (await importLibrary('maps'));

    // Set map options.
    const mapOptions = {
        center: { lat: 48.8566, lng: 2.3522 },
        zoom: 3,
    };

    // Declare the map.
    const map = new Map(
        document.getElementById('map') as HTMLElement,
        mapOptions
    );
}

initMap();
index.ts

JavaScript

// Import the needed libraries.
import { setOptions, importLibrary } from '@googlemaps/js-api-loader';
const API_KEY = 'AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8';
async function initMap() {
    // Set loader options.
    setOptions({
        key: API_KEY,
        v: 'weekly',
    });
    // Load the Maps library.
    const { Map } = (await importLibrary('maps'));
    // Set map options.
    const mapOptions = {
        center: { lat: 48.8566, lng: 2.3522 },
        zoom: 3,
    };
    // Declare the map.
    const map = new Map(document.getElementById('map'), mapOptions);
}
initMap();
index.js

Xem mã ví dụ hoàn chỉnh.

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 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 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ã xử lý ứng dụng:

  • Thay đổi hàm initMap() để hàm này 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();