Maps JavaScript API memungkinkan Anda menyesuaikan peta dengan konten dan gambar Anda sendiri untuk ditampilkan di halaman web dan perangkat seluler. Maps JavaScript API menampilkan empat jenis peta dasar (roadmap, satelit, hibrida, dan medan) yang dapat Anda ubah menggunakan lapisan dan gaya, kontrol dan peristiwa, serta berbagai layanan dan library.
Audiens
Dokumentasi ini didesain untuk orang yang memahami pemrograman JavaScript dan konsep pemrograman berorientasi objek. Anda juga harus memahami Google Maps dari sudut pandang pengguna. Ada banyak tutorial JavaScript yang tersedia di Web.
Dokumentasi konseptual ini dirancang untuk memungkinkan Anda secara cepat mulai menjelajahi dan mengembangkan aplikasi dengan Maps JavaScript API. Kami juga memublikasikan Referensi Maps JavaScript API.
Halo, Dunia
Cara termudah untuk mulai mempelajari Maps JavaScript API adalah melihat contoh sederhana. Contoh berikut menampilkan peta yang berpusat di Sydney, New South Wales, Australia.TypeScript
let map: google.maps.Map; function initMap(): void { map = new google.maps.Map(document.getElementById("map") as HTMLElement, { center: { lat: -34.397, lng: 150.644 }, zoom: 8, }); } declare global { interface Window { initMap: () => void; } } window.initMap = initMap;
JavaScript
let map; function initMap() { map = new google.maps.Map(document.getElementById("map"), { center: { lat: -34.397, lng: 150.644 }, zoom: 8, }); } window.initMap = initMap;
CSS
/* * Always set the map height explicitly to define the size of the div element * that contains the map. */ #map { height: 100%; } /* * Optional: Makes the sample page fill the window. */ html, body { height: 100%; margin: 0; padding: 0; }
HTML
<html> <head> <title>Simple Map</title> <script src="https://polyfill.io/v3/polyfill.min.js?features=default"></script> <link rel="stylesheet" type="text/css" href="./style.css" /> <script type="module" src="./index.js"></script> </head> <body> <div id="map"></div> <!-- The `defer` attribute causes the callback to execute after the full HTML document has been parsed. For non-blocking uses, avoiding race conditions, and consistent behavior across browsers, consider loading using Promises with https://www.npmjs.com/package/@googlemaps/js-api-loader. --> <script src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initMap&v=weekly" defer ></script> </body> </html>
Mencoba Contoh
Bahkan dalam contoh sederhana ini, ada beberapa hal yang perlu diperhatikan:
- Kami mendeklarasikan aplikasi sebagai HTML5 menggunakan deklarasi
<!DOCTYPE html>
. - Kami membuat elemen
div
bernama "map" untuk menyimpan peta. - Kami menentukan fungsi JavaScript yang membuat peta dalam
div
. - Kami memuat Maps JavaScript API menggunakan tag
script
.
Langkah-langkah ini dijelaskan di bawah.
Mendeklarasikan Aplikasi Anda sebagai HTML5
Sebaiknya deklarasikan DOCTYPE
sesungguhnya dalam aplikasi web Anda. Dalam contoh di sini, kami telah mendeklarasikan aplikasi sebagai HTML5 menggunakan DOCTYPE
HTML5 sederhana seperti yang ditampilkan di bawah ini:
<!DOCTYPE html>
Sebagian besar browser saat ini akan merender konten yang dideklarasikan dengan DOCTYPE
ini dalam "mode standar" yang berarti bahwa aplikasi Anda harus mematuhi persyaratan lintas browser. DOCTYPE
juga dirancang untuk menurunkan tingkat secara halus; browser yang tidak memahaminya akan mengabaikannya, dan menggunakan "mode quirks" untuk menampilkan kontennya.
Perhatikan, beberapa CSS yang bekerja dalam quirks mode tidak valid dalam mode standar. Secara khusus, semua ukuran berbasis-persentase harus mewarisi dari elemen blok induk, dan jika ada pendahulunya yang gagal menetapkan ukuran, maka dianggap berukuran 0 x 0 piksel. Oleh karena itu, kami menyertakan deklarasi <style>
berikut:
<style> #map { height: 100%; } html, body { height: 100%; margin: 0; padding: 0; } </style>
Deklarasi CSS ini menunjukkan bahwa penampung peta
<div>
(dengan ID map
) harus menempati 100% dari tinggi bodi
HTML. Perhatikan bahwa kami juga harus mendeklarasikan persentase tersebut untuk <body>
dan <html>
secara khusus.
Memuat Maps JavaScript API
Maps JavaScript API dimuat menggunakan tagscript
, yang dapat ditambahkan
secara inline di file HTML Anda atau secara dinamis menggunakan file JavaScript terpisah. Sebaiknya Anda meninjau
kedua pendekatan tersebut, lalu memilih salah satu pendekatan yang paling sesuai dengan struktur kode dalam
project Anda.
Pemuatan Inline
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>
Pemuatan Dinamis
Untuk memuat Maps JavaScript API secara dinamis menggunakan file JavaScript terpisah, lihat contoh di bawah. Pendekatan ini memungkinkan Anda menangani semua kode untuk menangani API dari file .js
terpisah, dan setara dengan menambahkan tag skrip secara inline.
// Create the script tag, set the appropriate attributes var script = document.createElement('script'); script.src = 'https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap'; script.async = true; // Attach your callback function to the `window` object window.initMap = function() { // JS API is loaded and available }; // Append the 'script' element to 'head' document.head.appendChild(script);
Pemuatan Dinamis
Paket @googlemaps/js-api-loader tersedia untuk membuat pengalaman pemuatan dinamis yang lebih lancar. Aplikasi ini dapat diinstal melalui NPM dengan hal 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(() => { map = new google.maps.Map(document.getElementById("map") as HTMLElement, { center: { lat: -34.397, lng: 150.644 }, zoom: 8, }); });
JavaScript
const loader = new Loader({ apiKey: "YOUR_API_KEY", version: "weekly", ...additionalOptions, }); loader.load().then(() => { map = new google.maps.Map(document.getElementById("map"), { center: { lat: -34.397, lng: 150.644 }, zoom: 8, }); });
Atribut Tag Skrip
Perhatikan pada contoh di atas bahwa beberapa atribut ditetapkan pada tag script
, yang direkomendasikan. Berikut adalah penjelasan dari setiap atribut.
src
: URL tempat Maps JavaScript API dimuat, termasuk semua simbol dan definisi yang Anda perlukan untuk menggunakan Maps JavaScript API. URL dalam contoh ini memiliki dua parameter:key
, tempat Anda memberikan kunci API, dancallback
, yang Anda gunakan untuk menentukan nama fungsi global yang akan dipanggil setelah Maps JavaScript API dimuat sepenuhnya. Baca selengkapnya tentang parameter URL.async
: Meminta browser untuk mendownload dan mengeksekusi skrip secara asinkron. Ketika dieksekusi, skrip akan memanggil fungsi yang ditentukan menggunakan parametercallback
.
Library
Saat memuat Maps JavaScript API melalui URL, Anda dapat memilih untuk memuat library tambahan melalui penggunaan parameter URL libraries
. Library adalah modul kode yang
menyediakan fungsi tambahan ke Maps JavaScript API utama, tetapi tidak
dimuat kecuali jika Anda memintanya secara khusus. Untuk
informasi selengkapnya, lihat
Library di Maps JavaScript API.
Memuat API secara sinkron
Dalam tag script
yang memuat Maps JavaScript API,
atribut defer
dan parameter
callback
dapat dihilangkan. Akibatnya, pemuatan API akan diblokir hingga API selesai
didownload.
Tindakan ini mungkin akan memperlambat pemuatan halaman. Namun itu berarti Anda bisa menulis tag script berikutnya dengan anggapan API tersebut sudah dimuat.
Elemen DOM Peta
<div id="map"></div>
Agar peta ditampilkan pada halaman web, kita harus menentukan tempat untuk menampilkannya.
Umumnya, kami melakukannya dengan membuat elemen div
bernama dan mendapatkan referensi ke elemen ini dalam document object model (DOM) browser.
Dalam contoh di atas, kita menggunakan CSS untuk menetapkan ketinggian div peta ke "100%". Ini akan diperluas agar ukurannya pada perangkat seluler sesuai. Anda mungkin perlu menyesuaikan nilai-nilai lebar dan tinggi berdasarkan ukuran layar dan padding browser. Perhatikan, div biasanya mengambil lebarnya dari elemen yang dimuatnya, dan div kosong biasanya memiliki ketinggian 0. Karena itu, Anda harus
selalu menetapkan tinggi secara eksplisit pada <div>
.
Opsi Peta
Ada dua opsi yang diperlukan untuk setiap peta: center
dan zoom
.
map = new google.maps.Map(document.getElementById('map'), { center: {lat: -34.397, lng: 150.644}, zoom: 8 });
Tingkat Zoom
Resolusi awal untuk menampilkan peta ditetapkan oleh
properti zoom
, dengan zoom 0
sesuai dengan peta Bumi yang diperkecil sepenuhnya, dan tingkat zoom yang lebih besar
akan memperbesar dengan resolusi yang lebih tinggi.
zoom: 8
Menampilkan peta seluruh Bumi sebagai gambar tunggal akan memerlukan peta yang teramat besar, atau peta kecil dengan resolusi sangat rendah. Akibatnya, gambar peta dalam Google Maps dan Maps JavaScript API akan dipecah menjadi "ubin" peta dan "tingkat zoom". Pada tingkat zoom rendah, satu rangkaian kecil ubin peta mencakup area yang luas; pada tingkat zoom yang lebih tinggi, ubin memiliki resolusi lebih tinggi dan mencakup area yang lebih kecil. Daftar berikut menampilkan perkiraan tingkat detail yang akan Anda lihat di setiap tingkat zoom:
- 1: Dunia
- 5: Daratan luas/benua
- 10: Kota
- 15: Jalan
- 20: Bangunan
Tiga gambar berikut memperlihatkan Tokyo dari lokasi yang sama pada tingkat zoom 0, 7 dan 18.
Untuk informasi tentang cara Maps JavaScript API memuat ubin berdasarkan tingkat zoom saat ini, lihat panduan untuk koordinat peta dan ubin.
Objek Peta
map = new google.maps.Map(document.getElementById("map"), {...});
Class JavaScript yang mewakili peta adalah class Map
.
Objek di class ini mendefinisikan sebuah peta pada halaman. (Anda bisa membuat lebih dari satu instance class ini — setiap objek akan mendefinisikan peta terpisah pada halaman.) Kita membuat instance baru dari class ini menggunakan operator
new
JavaScript.
Saat membuat instance peta baru, Anda menetapkan elemen HTML <div>
di halaman sebagai penampung untuk peta. Node HTML
adalah turunan dari objek document
JavaScript, dan
referensi ke elemen ini diperoleh melalui
metode document.getElementById()
.
Kode ini menentukan variabel (bernama map
) dan menetapkan variabel tersebut ke objek Map
baru. Fungsi Map()
dikenal sebagai konstruktor dan definisinya ditampilkan di bawah ini:
Konstruktor | Deskripsi |
---|---|
Map(mapDiv:Node, opts?:MapOptions
) |
Membuat peta baru di dalam penampung HTML tertentu — biasanya elemen DIV — menggunakan parameter (opsional) yang diteruskan. |
Memecahkan masalah
Error Kunci API dan Penagihan
Pada kondisi tertentu, peta gelap, atau gambar Street View 'negatif', yang diberi watermark dengan teks "hanya untuk tujuan pengembangan", mungkin ditampilkan. Perilaku ini biasanya mengindikasikan terjadi masalah pada kunci API atau penagihan. Untuk menggunakan produk Google Maps Platform, penagihan harus diaktifkan di akun Anda, dan semua permintaan harus menyertakan kunci API yang valid. Alur berikut akan membantu Anda memecahkan masalah ini:
Jika kode Anda tidak berfungsi:
Untuk membantu Anda menyiapkan dan menjalankan kode peta, Brendan Kenny dan Mano Marks menunjukkan beberapa kesalahan umum dan cara memperbaikinya dalam video ini.
- Cari kesalahan ketik. Ingatlah, JavaScript adalah bahasa yang peka huruf besar dan kecil.
- Periksa dasar-dasarnya - beberapa masalah yang paling umum terjadi saat awal pembuatan peta. Misalnya:
- Pastikan Anda telah menentukan properti
zoom
dancenter
di opsi peta Anda. - Pastikan Anda telah mendeklarasikan elemen div tempat peta akan muncul di layar.
- Pastikan elemen div untuk peta memiliki ketinggian. Secara default, elemen div dibuat dengan ketinggian 0, sehingga tidak terlihat.
- Pastikan Anda telah menentukan properti
- Gunakan debugger JavaScript untuk membantu mengidentifikasi masalah, seperti yang tersedia dalam Chrome Developer Tools. Mulailah dengan mencari error di konsol JavaScript.
- Posting pertanyaan ke Stack Overflow. Panduan tentang cara memposting pertanyaan bagus tersedia di halaman Dukungan.