Memuat Maps JavaScript API

Panduan ini menunjukkan cara memuat Maps JavaScript API. Ada tiga cara untuk melakukannya:

Menggunakan Dynamic Library Import

Muat Maps JavaScript API dengan menambahkan loader bootstrap inline ke kode aplikasi Anda, seperti yang ditunjukkan dalam cuplikan berikut:

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

Anda juga dapat menambahkan kode loader bootstrap langsung ke kode JavaScript Anda.

Untuk memuat library saat runtime, gunakan operator await untuk memanggil importLibrary() dari dalam fungsi async, seperti yang ditunjukkan dalam contoh kode berikut:

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

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

Parameter wajib

  • key: Kunci API Anda. Maps JavaScript API tidak akan dimuat kecuali jika kunci API yang valid ditentukan.

Parameter opsional

  • v: Versi Maps JavaScript API yang akan dimuat.

  • libraries: Daftar yang dipisahkan koma untuk library Maps JavaScript API tambahan yang akan dimuat. Menentukan serangkaian library yang tetap umumnya tidak direkomendasikan, tetapi tersedia bagi developer yang ingin secara mendetail menyesuaikan perilaku caching di situs mereka.

  • language: Bahasa yang akan digunakan. Parameter ini memengaruhi nama kontrol, pemberitahuan hak cipta, rute mobil, dan label kontrol, serta respons atas permintaan layanan. Lihat daftar bahasa yang didukung.

  • region: Kode wilayah yang akan digunakan. Parameter ini akan mengubah perilaku peta berdasarkan negara atau wilayah yang tertentu.

  • solutionChannel: Google Maps Platform menyediakan banyak jenis kode contoh untuk membantu Anda membuat peta dengan cepat. Untuk melacak penerapan contoh kode yang lebih kompleks dan meningkatkan kualitas solusi, Google menyertakan parameter kueri solutionChannel pada panggilan API dalam kode contoh kami.

  • authReferrerPolicy: Pelanggan Maps JS dapat mengonfigurasi Pembatasan Perujuk HTTP di Konsol Cloud untuk membatasi URL mana yang diizinkan untuk menggunakan kunci API tertentu. Secara default, pembatasan ini dapat dikonfigurasi untuk mengizinkan jalur tertentu saja yang dapat menggunakan Kunci API. Jika URL di domain atau origin yang sama dapat menggunakan Kunci API tersebut, Anda dapat menetapkan authReferrerPolicy: "origin" untuk membatasi jumlah data yang dikirim saat mengizinkan permintaan dari Maps JavaScript API. Jika parameter ini ditentukan dan Pembatasan Perujuk HTTP diaktifkan di Konsol Cloud, Maps JavaScript API hanya dapat dimuat jika ada Pembatasan Perujuk HTTP yang cocok dengan domain situs saat ini tanpa jalur yang ditentukan.

Menggunakan paket js-api-loader NPM

Paket @googlemaps/js-api-loader tersedia untuk dimuat melalui pengelola paket NPM. Instal paket ini menggunakan perintah berikut:

npm install @googlemaps/js-api-loader

Paket ini dapat diimpor ke dalam aplikasi dengan:

import { Loader } from "@googlemaps/js-api-loader"

Loader mengekspos antarmuka callback dan Promise. Berikut ini adalah contoh penggunaan metode Promise default 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

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

Lihat contoh yang menampilkan js-api-loader.

Menggunakan tag pemuatan skrip lama

Tag pemuatan skrip lama masih didukung. Bagian ini ditujukan untuk mendukung integrasi menggunakan tag pemuatan skrip lama. Google mengimbau Anda untuk bermigrasi ke Dynamic Library Loading API.

Menambahkan tag skrip

Untuk memuat Maps JavaScript API secara inline dalam file HTML, tambahkan tag script seperti yang ditunjukkan di bawah.

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

Parameter URL pemuatan skrip lama

Bagian ini membahas semua parameter yang dapat Anda tentukan dalam string kueri URL pemuatan skrip saat memuat Maps JavaScript API. Beberapa parameter tertentu wajib ditentukan sementara yang lainnya bersifat opsional. Sesuai dengan standar dalam URL, semua parameter dipisah menggunakan karakter ampersand (&).

Contoh URL berikut memiliki placeholder untuk semua kemungkinan parameter:

https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY
&callback=FUNCTION_NAME
&v=VERSION
&libraries="LIBRARIES"
&language="LANGUAGE"
&region="REGION"
&solution_channel="SOLUTION_IDENTIFIER"
&auth_referrer_policy="AUTH_REFERRER_POLICY"

URL dalam contoh tag script berikut memuat Maps JavaScript API:

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

Parameter wajib (lama)

Parameter berikut wajib ditentukan saat memuat Maps JavaScript API.

  • key: Kunci API Anda. Maps JavaScript API tidak akan dimuat kecuali jika kunci API yang valid ditentukan.

  • callback: Nama fungsi global yang akan dipanggil setelah Maps JavaScript API dimuat sepenuhnya.

Parameter opsional (lama)

Gunakan parameter berikut untuk meminta Maps JavaScript API versi tertentu, memuat library tambahan, melokalkan peta Anda, atau menentukan kebijakan pemeriksaan perujuk HTTP

  • v: Versi Maps JavaScript API yang akan digunakan.

  • libraries: Daftar yang dipisahkan koma untuk library Maps JavaScript API tambahan yang akan dimuat.

  • language: Bahasa yang akan digunakan. Hal ini memengaruhi nama kontrol, pemberitahuan hak cipta, rute mobil, dan label kontrol, serta respons atas permintaan layanan. Lihat daftar bahasa yang didukung.

  • region: Kode wilayah yang akan digunakan. Parameter ini akan mengubah perilaku peta berdasarkan negara atau wilayah yang tertentu.

  • solution_channel: Google Maps Platform menyediakan banyak jenis kode contoh untuk membantu Anda membuat peta dengan cepat. Untuk melacak penerapan contoh kode yang lebih kompleks dan meningkatkan kualitas solusi, Google menyertakan parameter kueri solution_channel pada panggilan API dalam kode contoh kami.

  • auth_referrer_policy: Pelanggan Maps JS dapat mengonfigurasi Pembatasan Perujuk HTTP di Konsol Cloud untuk membatasi URL mana yang diizinkan untuk menggunakan kunci API tertentu. Secara default, pembatasan ini dapat dikonfigurasi untuk mengizinkan jalur tertentu saja yang dapat menggunakan Kunci API. Jika URL di domain atau origin yang sama dapat menggunakan Kunci API tersebut, Anda dapat menetapkan auth_referrer_policy=origin untuk membatasi jumlah data yang dikirim saat mengizinkan permintaan dari Maps JavaScript API. Fitur ini tersedia mulai versi 3.46. Jika parameter ini ditentukan dan Pembatasan Perujuk HTTP diaktifkan di Konsol Cloud, Maps JavaScript API hanya dapat dimuat jika ada Pembatasan Perujuk HTTP yang cocok dengan domain situs saat ini tanpa jalur yang ditentukan.

Bermigrasi ke Dynamic Library Import API

Bagian ini membahas langkah-langkah yang diperlukan untuk memigrasikan integrasi Anda agar dapat menggunakan Dynamic Library Import API.

Langkah migrasi

Pertama, ganti tag pemuatan skrip lama dengan tag loader bootstrap inline.

Sebelum

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

Setelah

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

Selanjutnya, perbarui kode aplikasi Anda:

  • Ubah fungsi initMap() menjadi asinkron.
  • Panggil importLibrary() untuk memuat dan mengakses library yang Anda perlukan.

Sebelum

let map;

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

window.initMap = initMap;

Setelah

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