Setiap dasbor logistik, daftar real estat, dan aplikasi pengiriman makanan memiliki satu kesamaan: sebuah peta. Jika website Anda belum memilikinya, Anda membiarkan konteks tertinggal. Konteks yang membantu pengguna memahami lokasi, kedekatan, dan hubungan spasial dalam sekejap.
Tutorial ini memandu Anda menambahkan peta yang sepenuhnya interaktif ke proyek JavaScript apa pun. Anda akan mulai dengan peta yang dirender, menambahkan penanda dan popup, menghubungkan pencarian alamat dengan API Geocoding, dan selesai dengan komponen React yang siap produksi yang cocok rapi di Next.js.
Berikut yang akan Anda bangun di akhir:
- Peta vektor langsung yang diautentikasi dengan kunci API Anda
- Penanda yang dapat diklik dengan konten popup khusus
- Fungsi pencarian alamat yang didukung geocoding
- Komponen React yang dapat digunakan kembali dengan pembersihan yang tepat dan penanganan SSR Next.js
- Daftar periksa pengoptimalan kinerja untuk produksi
Prasyarat
Sebelum memulai, pastikan Anda memiliki:
- Kunci API MapAtlas (daftar gratis, tidak memerlukan kartu kredit). Kunci tunggal ini mengautentikasi setiap layanan MapAtlas: ubin, geocoding, dan routing.
- Proyek JavaScript. HTML biasa, React, Vue, atau Svelte semuanya berfungsi.
- Node.js 18+ jika Anda memasang melalui npm.
Langkah 1: Instal SDK MapAtlas
Tarik SDK ke proyek Anda dengan npm:
npm install @mapmetrics/mapmetrics-gl
Jika Anda bekerja dengan halaman HTML biasa, masukkan tautan CDN ke <head> Anda:
<link rel="stylesheet" href="https://unpkg.com/@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css" />
<script src="https://unpkg.com/@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.js"></script>
Jangan lewatkan impor CSS. Tanpanya, kontrol peta dan popup dirender tanpa gaya. Berfungsi, tetapi rusak secara visual.
Langkah 2: Buat Wadah Peta
SDK mengisi elemen apa pun yang Anda tunjukkan, jadi Anda memerlukan <div> dengan tinggi eksplisit. Ini adalah kesalahan pengaturan paling umum: jika wadah memiliki height: 0, peta diinisialisasi tetapi tetap tidak terlihat.
<div id="map" style="width: 100%; height: 500px;"></div>
Nilai piksel tetap atau unit viewport (100vh, 50vh) keduanya berfungsi. Tinggi persentase hanya berfungsi jika elemen induk juga memiliki tinggi yang ditentukan.
Langkah 3: Render Peta Interaktif Pertama Anda
Tiga baris konfigurasi adalah semua yang diperlukan: wadah, URL gaya dengan kunci API Anda, dan posisi awal.
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';
const map = new mapmetricsgl.Map({
container: 'map',
style: 'https://tiles.mapatlas.eu/styles/basic/style.json?key=YOUR_API_KEY',
center: [4.9041, 52.3676],
zoom: 12,
});
Buka halaman dan Anda akan melihat peta vektor yang dapat Anda seret, gulir, dan cubit untuk menavigasi. Ubin dimuat sesuai permintaan dari server MapAtlas, jadi tidak ada unduhan berat di awal.
Memilih Gaya Peta
Tukar segmen jalur di URL gaya untuk mengubah tampilan sepenuhnya:
| Gaya | Jalur URL | Terbaik untuk |
|---|---|---|
| Basic | /styles/basic/style.json | Aplikasi tujuan umum |
| Bright | /styles/bright/style.json | Overlay visualisasi data |
| Dark | /styles/dark/style.json | Dasbor, mode malam, analitik |
Kemenangan cepat: Gunakan gaya Dark untuk panel admin dan alat yang digunakan di lingkungan cahaya rendah. Ini mengurangi ketegangan mata dan membuat lapisan data seperti heatmap dan jalur rute menonjol secara visual terhadap latar belakang.
Langkah 4: Tambahkan Penanda dan Popup ke Peta Anda
Peta tanpa penanda hanya sekadar gambar latar belakang. Penanda mengubah tampilan statis menjadi sesuatu yang dapat berinteraksi dengan pengguna.
Penanda Tunggal dengan Popup
const popup = new mapmetricsgl.Popup().setHTML(`
<strong>Amsterdam Central</strong>
<p>Stationsplein, 1012 AB Amsterdam</p>
`);
new mapmetricsgl.Marker({ color: '#97C70A' })
.setLngLat([4.9001, 52.3791])
.setPopup(popup)
.addTo(map);
Klik penanda dan popup terbuka. Anda dapat memasukkan HTML apa pun di dalamnya: alamat, thumbnail, tombol CTA, apa pun yang diperlukan UI Anda.
Memplot Beberapa Penanda dari Data
Sebagian besar aplikasi dunia nyata memerlukan lebih dari satu pin. Loop melalui array dan buat penanda untuk setiap entri:
const locations = [
{ name: 'Amsterdam', coords: [4.9041, 52.3676] },
{ name: 'Rotterdam', coords: [4.4777, 51.9244] },
{ name: 'Utrecht', coords: [5.1214, 52.0907] },
];
locations.forEach(({ name, coords }) => {
const popup = new mapmetricsgl.Popup().setHTML(`<strong>${name}</strong>`);
new mapmetricsgl.Marker({ color: '#97C70A' })
.setLngLat(coords)
.setPopup(popup)
.addTo(map);
});
Catatan kinerja: Setelah Anda melampaui kurang lebih 100 hingga 200 penanda, rendering melambat terlihat pada tampilan yang diperbesar keluar. Aktifkan pengelompokan sumber GeoJSON (didukung out of the box oleh SDK) untuk mengelompokkan penanda terdekat pada tingkat zoom rendah. Periksa dokumentasi SDK untuk konfigurasi pengelompokan.
Langkah 5: Tambahkan Pencarian Alamat dengan API Geocoding
API Geocoding mengubah kueri teks (alamat jalan, nama kota, atau landmark) menjadi koordinat yang dapat Anda luncurkan, tandai, atau masukkan ke permintaan routing.
async function searchAddress(query) {
const url = new URL('https://api.mapatlas.eu/geocoding/v1/search');
url.searchParams.set('text', query);
url.searchParams.set('key', 'YOUR_API_KEY');
const res = await fetch(url);
const data = await res.json();
if (!data.features.length) return;
const [lng, lat] = data.features[0].geometry.coordinates;
const label = data.features[0].properties.label;
map.flyTo({ center: [lng, lat], zoom: 14 });
new mapmetricsgl.Marker({ color: '#97C70A' })
.setLngLat([lng, lat])
.setPopup(new mapmetricsgl.Popup().setHTML(`<strong>${label}</strong>`))
.addTo(map);
}
searchAddress('Rijksmuseum, Amsterdam');
Hasil kembali sebagai fitur GeoJSON, jadi mereka terhubung langsung ke lapisan apa pun yang kompatibel dengan GeoJSON, tabel data, atau panggilan API hilir.
Bangun bilah pencarian langsung dalam waktu kurang dari 30 baris: Lampirkan
searchAddresske peristiwainputdari bidang teks, debounce selama 300ms, dan Anda memiliki pencarian peta gaya autocomplete tanpa ketergantungan tambahan.
Mengintegrasikan Peta Interaktif dengan React
Komponen Peta yang Dapat Digunakan Kembali
Bungkus inisialisasi peta dalam useEffect agar berjalan setelah DOM dipasang, dan kembalikan fungsi pembersihan untuk mencegah kebocoran memori saat unmount:
import { useEffect, useRef } from 'react';
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';
export function MapAtlasMap({ apiKey, center = [4.9041, 52.3676], zoom = 12 }) {
const containerRef = useRef(null);
useEffect(() => {
const map = new mapmetricsgl.Map({
container: containerRef.current,
style: `https://tiles.mapatlas.eu/styles/basic/style.json?key=${apiKey}`,
center, zoom,
});
return () => map.remove();
}, [apiKey]);
return <div ref={containerRef} style={{ width: '100%', height: '500px' }} />;
}
Gunakan di mana saja dalam pohon komponen Anda:
<MapAtlasMap apiKey={process.env.NEXT_PUBLIC_MAPATLAS_KEY} center={[4.9041, 52.3676]} zoom={13} />
Menangani Rendering Sisi Server Next.js
SDK peta bergantung pada API browser (window, document) yang tidak ada selama SSR. Impor komponen secara dinamis dengan SSR dinonaktifkan:
import dynamic from 'next/dynamic';
const MapAtlasMap = dynamic(
() => import('./MapAtlasMap').then(m => m.MapAtlasMap),
{ ssr: false, loading: () => (<div style={{ height: 500, background: '#f0f1f3', borderRadius: 12 }} />) }
);
Placeholder loading menjaga tata letak Anda tetap stabil saat bundel peta diunduh, mencegah cumulative layout shift (CLS), yang penting untuk pengalaman pengguna dan Core Web Vitals.
Daftar Periksa Kinerja Produksi
Sebelum diluncurkan, jalankan pengoptimalan ini:
- Peta lazy-load di bawah lipatan. Gunakan
IntersectionObserveruntuk menginisialisasi peta hanya saat wadahnya bergulir ke dalam tampilan. Ini menunda ~200 KB JavaScript dari pemuatan halaman awal. - Tahan dengan ubin vektor. Ubin vektor skala dengan bersih ke kepadatan layar apa pun, memuat lebih cepat daripada gambar raster, dan dapat diberi gaya ulang sisi klien tanpa permintaan server tambahan. MapAtlas melayani ubin vektor secara default.
- Kelompokkan set penanda besar. Melampaui 100 hingga 200 penanda, rendering tanpa pengelompokan pada tampilan yang diperbesar keluar menyebabkan penurunan frame yang terlihat. Pengelompokan menyelesaikan ini sepenuhnya.
- Simpan kunci API Anda di sisi server. Jangan pernah melakukan commit kunci ke repositori publik. Gunakan variabel lingkungan (
NEXT_PUBLIC_MAPATLAS_KEYdi Next.js) atau proxy permintaan melalui backend Anda untuk operasi sensitif. - Atur
maxBoundsuntuk aplikasi regional. Jika pengguna Anda hanya peduli dengan satu geografi, batasi viewport sehingga ubin di luar area itu tidak pernah diminta. Lebih sedikit panggilan jaringan, pemuatan lebih cepat.
Apa yang Akan Dibangun Selanjutnya
Anda memiliki peta yang dirender, menampilkan penanda, mencari alamat, dan terintegrasi dengan React. Inilah tempat untuk melanjutkan:
- Routing API: Minta petunjuk belokan demi belokan antara dua koordinat. Mengembalikan polyline rute, jarak total, dan waktu tempuh yang diperkirakan.
- Isochrone API: Hasilkan poligon yang mencakup setiap titik yang dapat dicapai dalam n menit. Digunakan untuk zona pengiriman, peta cakupan layanan, dan analisis area tangkapan.
- Matrix API: Hitung waktu tempuh dan jarak antara beberapa asal dan tujuan dalam satu permintaan. Penting untuk pengiriman armada dan optimasi logistik.
Referensi SDK lengkap, dokumentasi gaya, dan panduan API tersedia di docs.mapatlas.xyz.
Pertanyaan Umum
Bisakah saya menambahkan peta interaktif ke website saya secara gratis?
Ya. MapAtlas menawarkan tingkat gratis tanpa kartu kredit yang diperlukan saat pendaftaran. Ini mencakup rendering ubin vektor, API Geocoding, dan API Routing. Itu cukup untuk pengembangan dan penggunaan produksi skala kecil.
Bagaimana cara menyematkan peta di aplikasi React atau Next.js?
Bungkus inisialisasi peta dalam hook useEffect agar berjalan setelah DOM dipasang. Di Next.js, gunakan dynamic() dengan ssr: false untuk menghindari kesalahan rendering sisi server. Kedua pendekatan tercakup dengan contoh copy-paste dalam tutorial ini.
Apa itu ubin vektor, dan mengapa saya harus menggunakannya di atas raster?
Ubin vektor menggambarkan fitur peta (jalan, bangunan, label) sebagai geometri matematis daripada gambar piksel pra-render. Mereka skala tajam ke resolusi apa pun, unduh lebih cepat, dan dapat diberi gaya ulang sepenuhnya di klien tanpa putaran server tambahan.
Berapa banyak penanda yang dapat saya tambahkan sebelum kinerja menurun?
Rendering biasanya menurun melampaui 100 hingga 200 penanda pada tingkat zoom rendah. Perbaikannya adalah pengelompokan: SDK MapAtlas mendukung pengelompokan sumber GeoJSON secara native, mengelompokkan penanda terdekat pada zoom rendah dan memperluas saat pengguna zoom masuk.
Apakah saya memerlukan pengalaman GIS untuk menggunakan MapAtlas?
Tidak. SDK dirancang untuk pengembang web, bukan spesialis GIS. Anda menginisialisasi peta dengan koordinat dan tingkat zoom, menambahkan penanda dengan pasangan bujur/lintang, dan memanggil API Geocoding dengan teks biasa. Tidak ada database spasial atau peralatan GIS yang diperlukan.
