Places UI Kit: Một thư viện có thể sử dụng ngay, cung cấp không gian tuỳ chỉnh và kiểm soát cho nhà phát triển. Hãy dùng thử và chia sẻ ý kiến của bạn về trải nghiệm dùng Bộ giao diện người dùng.

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Tải Maps JavaScript API

Hướng dẫn này cho bạn biết cách tải Maps JavaScript API. Bạn có thể thực hiện việc này theo 3 cách:

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 cho phép 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 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 nạp khởi động cùng dòng vào mã xử lý ứng dụng của bạn, như 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 nạp 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() 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ư trong ví dụ về mã sau:

async function init() {
    // Import the needed libraries.
    await google.maps.importLibrary('maps');

    // Access the map.
    const mapElement = document.querySelector('gmp-map');
    // Access the underlying map object.
    const innerMap = mapElement.innerMap;

    console.log({ mapElement, innerMap });
}

void init();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 thư viện trực tiếp trong HTML như minh hoạ sau:

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

Tham 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ệ.

Tham 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. Bạn thường không nên chỉ định một tập hợp thư viện cố định, nhưng nhà phát triển có thể sử dụng tính năng này nếu muốn điều chỉnh chi tiết hành vi lưu vào bộ nhớ đệm trên trang web của mình. 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. Ngôn ngữ 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. Mã này 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 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 cho phép 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 nào được chỉ định.
mapIds: Một mảng mã bản đồ. Yêu cầu tải trước cấu hình cho các mã bản đồ được chỉ định. 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à phát triển có thể sử dụng tính năng này nếu muốn điều chỉnh chi tiết hiệu suất mạng.
channel: Xem phần Theo dõi mức sử dụng theo kênh.

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

Thêm thẻ tập lệnh

Để tải Maps JavaScript API nội tuyến 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>

Tham 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ệ.

Tham 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 tham số 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 chung sẽ được gọi sau khi Maps JavaScript API tải hoàn toàn.
v: Phiên bản Maps JavaScript API cần sử dụng.
libraries: Danh sách các thư viện Maps JavaScript API bổ sung cần tải, được phân tách bằng dấu phẩy.
language: Ngôn ngữ cần sử dụng. Ngôn ngữ 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. Mã này 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 cho phép 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 nào được chỉ định.
map_ids: 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. 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à phát triển có thể sử dụng tính năng này nếu muốn điều chỉnh chi tiết hiệu suất mạng.
channel: Xem phần Theo dõi mức sử dụng theo kênh.

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

Bạn có thể sử dụng gói @googlemaps/js-api-loader để 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ạ sau:

TypeScript

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

JavaScript

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

Trình tải sử dụng Lời hứa để cung cấp thư viện. Tải thư viện bằng phương thức importLibrary(). Ví dụ sau 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 init(): Promise<void> {
    // Set loader options.
    setOptions({
        key: API_KEY,
    });

    // 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.
    new Map(document.getElementById('map')!, mapOptions);
}

void init();index.ts

JavaScript

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

const API_KEY = 'AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8';

async function init() {
    // Set loader options.
    setOptions({
        key: API_KEY,
    });

    // 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.
    new Map(document.getElementById('map'), mapOptions);
}

void init();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 của bạn sang 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 nạp khởi động nội tuyến.

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

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

let map;

function initMap() {
  map = new google.maps.Map(document.getElementById("map"), {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

window.initMap = initMap;

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

Tải Maps JavaScript API

Sử dụng tính năng nhập thư viện động

Tham số bắt buộc

Tham số tuỳ chọn

Sử dụng thẻ tải tập lệnh trực tiếp

Thêm thẻ tập lệnh

Tham số URL tải tập lệnh trực tiếp

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

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

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

TypeScript

JavaScript

TypeScript

JavaScript

Di chuyển sang API Nhập thư viện động

Các bước di chuyển

Trước

Sau

Trước

Sau

Tải Maps JavaScript API Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

Sử dụng tính năng nhập thư viện động

Tham số bắt buộc

Tham số tuỳ chọn

Sử dụng thẻ tải tập lệnh trực tiếp

Thêm thẻ tập lệnh

Tham số URL tải tập lệnh trực tiếp

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

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

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

TypeScript

JavaScript

TypeScript

JavaScript

Di chuyển sang API Nhập thư viện động

Các bước di chuyển

Trước

Sau

Trước

Sau

Tải Maps JavaScript API