Memuat Maps JavaScript API

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

Menggunakan dynamic library import
Gunakan tag pemuatan skrip langsung
Menggunakan paket js-api-loader NPM

Menggunakan Dynamic Library Import

Dynamic library import menyediakan kemampuan untuk memuat library saat runtime. Hal ini memungkinkan Anda meminta library yang diperlukan pada saat Anda membutuhkannya, bukan semuanya sekaligus saat waktu pemuatan. Cara ini juga melindungi halaman Anda dari pemuatan 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. Mendeklarasikan variabel untuk class yang diperlukan memungkinkan Anda melewati penggunaan jalur yang memenuhi syarat (misalnya google.maps.Map), seperti yang ditunjukkan dalam contoh kode berikut:

async function initMap() {
    // Import the needed libraries.
    await google.maps.importLibrary('maps');
    // Create the map.
    const mapElement = document.querySelector('gmp-map');
    // Access the underlying map object.
    const innerMap = mapElement.innerMap;
}
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. Tanpa variabel, Anda harus menggunakan jalur yang memenuhi syarat, misalnya 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();

Atau, Anda dapat memuat library 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 yang diperlukan

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: Array library Maps JavaScript API tambahan untuk mulai dimuat sebelumnya. Menentukan serangkaian library yang tetap umumnya tidak direkomendasikan, tetapi tersedia bagi developer yang ingin secara mendetail menyesuaikan perilaku caching di situs mereka. Anda tetap harus memanggil google.maps.importLibrary() untuk setiap library yang dipilih sebelum digunakan.
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 API 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. Menentukan ID peta di sini tidak diperlukan untuk penggunaan ID peta, tetapi tersedia bagi developer yang ingin secara mendetail menyesuaikan performa jaringan.
channel: Lihat Pelacakan penggunaan per channel.

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 menghilangkan 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. Parameter tertentu diperlukan, sedangkan parameter 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 yang diperlukan (langsung) {:.hide-from-toc}

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) {:.hide-from-toc}

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 parameter ini ke async jika memungkinkan, untuk meningkatkan performa. (Gunakan parameter callback sebagai gantinya 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. 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 API 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.
map_ids: Daftar ID peta yang dipisahkan koma. Menyebabkan konfigurasi untuk ID peta yang ditentukan dimuat sebelumnya. Menentukan ID peta di sini tidak diperlukan untuk penggunaan ID peta, tetapi tersedia bagi developer yang ingin secara mendetail menyesuaikan performa jaringan.
channel: Lihat Pelacakan penggunaan per channel.
internal_usage_attribution_ids: Daftar yang dipisahkan koma untuk ID atribusi penggunaan yang membantu Google memahami library dan contoh mana yang bermanfaat bagi developer, seperti penggunaan library pengelompokan penanda. Untuk memilih tidak mengirim ID atribusi penggunaan, Anda dapat menghapus properti ini atau mengganti nilainya dengan string kosong. Hanya nilai unik yang akan dikirim. Lihat parameter solusi Google Maps Platform untuk mengetahui informasi selengkapnya.

Catatan: Parameter solution_channel masih valid, tetapi tidak direkomendasikan. Gunakan internal_usage_attribution_ids sebagai gantinya.

Menggunakan paket js-api-loader NPM

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

npm install @googlemaps/js-api-loader

Impor paket seperti yang ditunjukkan di sini:

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

Loader menggunakan Promise untuk menyediakan library. Muat library menggunakan metode importLibrary(). Contoh berikut menunjukkan penggunaan loader untuk memuat peta:

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

Lihat contoh kode lengkap.

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

Memuat Maps JavaScript API Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Menggunakan Dynamic Library Import

Parameter yang diperlukan

Parameter opsional

Menggunakan tag pemuatan skrip langsung

Menambahkan tag skrip

Parameter URL pemuatan skrip langsung

Parameter yang diperlukan (langsung) {:.hide-from-toc}

Parameter opsional (langsung) {:.hide-from-toc}

Menggunakan paket js-api-loader NPM

TypeScript

JavaScript

TypeScript

JavaScript

Bermigrasi ke Dynamic Library Import API

Langkah migrasi

Sebelum

Setelah

Sebelum

Setelah

Memuat Maps JavaScript API