Memuat Maps JavaScript API

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

• Menggunakan impor library dinamis
• Menggunakan tag pemuatan skrip langsung
• Menggunakan paket js-api-loader NPM

Menggunakan Dynamic Library Import

Impor library dinamis menyediakan kemampuan untuk memuat library saat runtime. Hal ini memungkinkan Anda meminta library yang diperlukan pada saat Anda membutuhkannya, bukan secara sekaligus pada waktu pemuatan. Hal ini juga melindungi halaman Anda agar tidak memuat Maps JavaScript API beberapa kali.

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. Dengan mendeklarasikan variabel untuk class yang diperlukan, Anda dapat mengabaikan penggunaan jalur yang memenuhi syarat (misalnya, google.maps.Map), seperti yang ditunjukkan dalam contoh kode berikut:

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

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

Fungsi Anda juga dapat memuat library tanpa mendeklarasikan variabel untuk class yang diperlukan, yang sangat berguna jika Anda menambahkan peta menggunakan elemen gmp-map:

async function initMap() {
  google.maps.importLibrary("maps");
  google.maps.importLibrary("marker");
}

initMap();

Atau, Anda dapat memuat library secara langsung di HTML seperti yang ditunjukkan di sini:

<script>
google.maps.importLibrary("maps");
google.maps.importLibrary("marker");
</script>

Pelajari cara bermigrasi ke Dynamic Library Loading API.

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.

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

• mapIds: Array ID peta. Menyebabkan konfigurasi untuk ID peta yang ditentukan dimuat sebelumnya.

• channel: Lihat Pelacakan penggunaan per saluran.

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

Menggunakan tag pemuatan skrip langsung

Bagian ini menunjukkan cara menggunakan tag pemuatan skrip langsung. Karena skrip langsung memuat library saat peta dimuat, skrip ini dapat menyederhanakan peta yang dibuat menggunakan elemen gmp-map dengan menghapus kebutuhan untuk meminta library secara eksplisit saat runtime. Karena tag pemuatan skrip langsung memuat semua library yang diminta sekaligus saat skrip dimuat, performa dapat terpengaruh untuk beberapa aplikasi. Hanya sertakan tag pemuatan skrip langsung sekali per pemuatan halaman.

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&loading=async&callback=initMap">
</script>

Parameter URL pemuatan skrip langsung

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
&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 dalam contoh tag script berikut memuat Maps JavaScript API:

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

Parameter wajib (langsung)

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.

Parameter opsional (langsung)

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

• loading: Strategi pemuatan kode yang dapat digunakan Maps JavaScript API. Tetapkan ke async untuk menunjukkan bahwa Maps JavaScript API belum dimuat secara sinkron dan tidak ada kode JavaScript yang dipicu oleh peristiwa load skrip. Sebaiknya tetapkan setelan ini ke async jika memungkinkan, untuk meningkatkan performa. (Gunakan parameter callback untuk melakukan tindakan saat Maps JavaScript API tersedia.) Tersedia mulai versi 3.55.

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

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

• auth_referrer_policy: Pelanggan 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.

• mapIds: Daftar ID peta yang dipisahkan koma. Menyebabkan konfigurasi untuk ID peta yang ditentukan dimuat sebelumnya.

• channel: Lihat Pelacakan penggunaan per saluran.

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

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

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

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.

Contoh berikut menunjukkan penggunaan loader.importLibrary() untuk memuat library:

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

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 langsung dengan tag loader bootstrap inline.

Sebelum

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&libraries=maps&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();