Her lojistik panosunun, gayrimenkul ilanının ve yemek teslimat uygulamasının ortaklaştığı bir şey vardır: bir harita. Web sitenizde henüz bir tane yoksa, bağlam açısından geri kalıyorsunuz. Kullanıcılara konum, yakınlık ve mekansal ilişkileri bir bakışta anlamalarına yardımcı olan bağlam.
Bu öğretici size herhangi bir JavaScript projesine tam etkileşimli bir harita ekleme sürecinde rehberlik eder. Oluşturulmuş bir haritayla başlayacaksınız, işaretçiler ve açılır pencereler ekleyeceksiniz, Coğrafi Kodlama API'siyle adres aramasını bağlayacaksınız ve Next.js'ye temiz bir şekilde düşen üretime hazır bir React bileşeniyle biteceksiniz.
İşte sonunda oluşturacağınız şeyler:
- API anahtarınızla doğrulanmış canlı bir vektör harita
- Özel açılır pencere içeriğine sahip tıklanabilir işaretçiler
- Coğrafi kodlama tarafından desteklenen bir adres arama işlevi
- Uygun temizlik ve Next.js SSR işlemeyle yeniden kullanılabilir bir React bileşeni
- Üretim için performans optimizasyonları kontrol listesi
Ön Koşullar
Başlamadan önce şunlara sahip olduğunuzdan emin olun:
- Bir MapAtlas API anahtarı (ücretsiz kaydolun, kredi kartı gerekli değil). Bu tek anahtar tüm MapAtlas hizmetlerini doğrular: kutucuklar, coğrafi kodlama ve yönlendirme.
- Bir JavaScript projesi. Düz HTML, React, Vue veya Svelte hepsi işler.
- Node.js 18+ npm üzerinden kuruyorsanız.
Adım 1: MapAtlas SDK'yı Yükleyin
SDK'yı npm ile projenize çekin:
npm install @mapmetrics/mapmetrics-gl
Bunun yerine düz bir HTML sayfasıyla çalışıyorsanız, CDN bağlantılarını <head> konumunuza bırakın:
<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>
CSS içe aktarımını atlayın. Bunu olmadan, harita denetimleri ve açılır pencereler stili olmayan olarak oluşturulur. İşlevsel ama görsel olarak bozuk.
Adım 2: Harita Kapsayıcı Oluşturun
SDK, ona işaret ettiğiniz herhangi bir öğeyi doldurur, bu nedenle açık yüksekliğe sahip bir <div> gerekir. Bu en yaygın kurulum hatası: konteyner height: 0 varsa, harita başlatılır ancak görünmez kalır.
<div id="map" style="width: 100%; height: 500px;"></div>
Sabit piksel değeri veya viewport birimi (100vh, 50vh) her ikisi de çalışır. Yüzde yükseklikleri yalnızca ana eleman da tanımlanmış bir yüksekliğe sahipse çalışır.
Adım 3: İlk Etkileşimli Haritanızı Oluşturun
Yapılandırmanın tamamı üç satırla yapılır: bir kapsayıcı, API anahtarınızla stil URL'si ve başlangıç konumu.
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,
});
Sayfayı açın ve sürükleyebileceğiniz, kaydırabileceğiniz ve sabitlseki gezinmek için sıkabileceğiniz bir vektör harita göreceksiniz. Kutucuklar MapAtlas sunucularından talep üzerine yüklenir, bu nedenle ön yükleme ağır değil.
Harita Stili Seçin
Görünümü tamamen değiştirmek için stil URL'sindeki yol segmentini değiştirin:
| Stil | URL Yolu | En İyi |
|---|---|---|
| Basic | /styles/basic/style.json | Genel amaçlı uygulamalar |
| Bright | /styles/bright/style.json | Veri görselleştirme kaplaması |
| Dark | /styles/dark/style.json | Panolar, gece modu, analitikler |
Hızlı kazanç: Düşük ışık ortamlarında kullanılan yönetici panelleri ve araçlar için Koyu stilini kullanın. Göz yorgunluğunu azaltır ve ısı haritaları ve rota çizgileri gibi veri katmanlarının arka plana karşı görsel olarak vurgulanmasını sağlar.
Adım 4: Haritanıza İşaretçiler ve Açılır Pencereler Ekleyin
İşaretçi olmayan bir harita sadece arka plan görüntüsüdür. İşaretçiler statik bir görünümü kullanıcıların etkileşim kurabileceği bir şeye dönüştürür.
Açılır Pencereli Tek İşaretçi
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);
İşaretçiye tıklayın ve açılır pencere açılır. İçine herhangi bir HTML koyabilirsiniz: adresler, küçük resimler, eylem çağrısı düğmeleri, UI'nızın gerektirdiği her şey.
Verilerden Birden Çok İşaretçi Çizme
Çoğu gerçek dünya uygulamasının birden fazla pin'e ihtiyacı vardır. Bir dizi üzerinde döngü yapın ve her giriş için bir işaretçi oluşturun:
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);
});
Performans notu: Yaklaşık 100 ila 200 işaretçiyi aştığınızda, yakınlaştırılmış görünümlerde işleme kayda değer yavaşlar. GeoJSON kaynağı kümelemeyi etkinleştirin (SDK tarafından kutunun dışında desteklenen) düşük yakınlaştırma düzeylerinde yakındaki işaretçileri gruplandırmak için. Kümeleme yapılandırması için SDK belgelerine bakın.
Adım 5: Coğrafi Kodlama API'siyle Adres Araması Ekleyin
Coğrafi Kodlama API'si bir metin sorgusunu (bir sokak adresi, şehir adı veya yer işareti) haritasında yapabilir, işaretleyebilir veya bir yönlendirme isteğine besleyebileceğiniz koordinatlara dönüştürür.
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');
Sonuçlar GeoJSON özelikleri olarak döner, bu nedenle herhangi bir GeoJSON uyumlu katmana, veri tablosuna veya sonraki API çağrısına doğrudan takılırlar.
30 satırdan az canlı bir arama çubuğu oluşturun:
searchAddressöğesini bir metin alanınıninputolayına ekleyin, 300ms tarafından debounce yapın ve otomatik tamamlama stilinde harita araması elde edersiniz. Hiçbir ek bağımlılık yok.
Etkileşimli Haritaları React ile Entegre Etme
Yeniden Kullanılabilir Harita Bileşeni
Harita başlatmayı useEffect içinde sarın, böylece DOM bağlandıktan sonra çalışır ve kaldırma sırasında bellek sızıntılarını önlemek için bir temizleme işlevi döndürün:
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' }} />;
}
Bileşen ağacınızda herhangi bir yerde kullanın:
<MapAtlasMap apiKey={process.env.NEXT_PUBLIC_MAPATLAS_KEY} center={[4.9041, 52.3676]} zoom={13} />
Next.js Sunucu Tarafı Oluşturmayı İşleme
Harita SDK'sı SSR sırasında var olmayan tarayıcı API'lerine (window, document) bağlıdır. Bileşeni SSR devre dışı bırakılmış şekilde dinamik olarak alın:
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 }} />) }
);
loading yer tutucu, harita paketi indirilirken düzeninizi kararlı tutar, bunu hem kullanıcı deneyimi hem de Core Web Vitals açısından önemli olan kümülatif mizanpaj kaymasını (CLS) önler.
Üretim Performans Kontrol Listesi
Sevkiyat yapmadan önce bu optimizasyonları gözden geçirin:
- Katlan altındaki haritaları tembel yükle. Harita başlatmayı yalnızca kapsayıcısı görünüme kaydığında yapmak için
IntersectionObserverkullanın. Bu, başlangıç sayfa yükünden yaklaşık 200 KB JavaScript'i erteler. - Vektör kutucuklarına bağlı kalın. Vektör kutucukları herhangi bir ekran yoğunluğuna temiz bir şekilde ölçeklendirir, raster görselleri yükler ve ek sunucu istekleri olmadan istemci tarafında yeniden stillenebilir. MapAtlas varsayılan olarak vektör kutucukları sunmaktadır.
- Büyük işaretçi kümelerini kümelendirir. 100 ila 200 işaretçi olmanız, yakınlaştırılmış bir görünümde kümesiz işleme belirgin kare düşmelerine neden olur. Kümeleme bunu tamamen çözer.
- API anahtarınızı sunucu tarafında tutun. Anahtarları ortak bir depo içine asla işlemeyin. Hassas işlemler için ortam değişkenleri (
NEXT_PUBLIC_MAPLATLAS_KEYiçinde Next.js) kullanın veya istekleri arka uç aracılığıyla proxy yapın. - Bölgesel uygulamalar için
maxBoundsayarlayın. Kullanıcılarınız yalnızca bir coğrafya hakkında endişe duyuyorsa, o alan dışındaki kutucuklar asla istenmez şekilde viewport'u kısıtlayın. Daha az ağ çağrısı, daha hızlı yükleme.
Sonra Ne Oluşturacağız
Oluşturduğunuz harita işlenmekte, işaretçiler göstermekte, adresler aramakta ve React ile entegre olmaktadır. Buradan nereye gideceğiniz:
- Routing API: İki koordinat arasında turna talimatları isteyin. Bir rota polilinesi, toplam mesafe ve tahmini seyahat süresini döndürür.
- Isochrone API: n dakika içinde ulaşılabilir her noktayı kapsayan bir çokgen oluşturun. Teslimat bölgeleri, hizmet kapsama haritaları ve yakalama alanı analizi için kullanılır.
- Matrix API: Birden çok başlangıç ve hedef arasında seyahat süresi ve mesafesini tek bir istekte hesaplayın. Filo gönderimi ve lojistik optimizasyonu için gerekli.
SDK başvurusu, stil belgeleri ve API kılavuzları docs.maplatlas.xyz adresinde mevcuttur.
Sıkça Sorulan Sorular
Web sitelerime ücretsiz olarak etkileşimli harita ekleyebilir miyim?
Evet. MapAtlas, kayıt sırasında kredi kartı gerekli olmaksızın ücretsiz bir katman sunar. Vektör kutucuk oluşturmayı, Coğrafi Kodlama API'sini ve Yönlendirme API'sini içerir. Bu, geliştirme ve küçük ölçekli üretim kullanımı için yeterlidir.
React veya Next.js uygulamasına bir harita nasıl gömem?
Harita başlatmayı DOM bağlandıktan sonra çalışması için useEffect kancasında sarın. Next.js'de, sunucu tarafı oluşturma hatalarını önlemek için ssr: false ile dynamic() kullanın. Her iki yaklaşım da bu öğreticide kopyala-yapıştır örnekleriyle ele alınmıştır.
Vektör kutucukları nedir ve bunları raster yerine neden kullanmalıyım?
Vektör kutucukları harita özelliklerini (yollar, binalar, etiketler) önceden işlenmiş piksel görüntüleri yerine matematiksel geometri olarak tanımlar. Herhangi bir çözünürlüğe temiz bir şekilde ölçeklendirir, raster görüntüleri yükler ve ek sunucu turları olmadan istemcide tamamen yeniden stillenebilir.
Performans düşmeden önce kaç işaretçi ekleyebilirim?
Rendering genellikle düşük yakınlaştırma seviyelerinde 100 ila 200 işaretçinin ötesinde bozulur. Düzeltme kümeleme: MapAtlas SDK, GeoJSON kaynağı kümelemeyi yerel olarak destekler, düşük yakınlaştırma düzeylerinde yakındaki işaretçileri gruplandırdığınız ve kullanıcı yakınlaştıkça açılır.
MapAtlas'ı kullanmak için GIS deneyimine ihtiyacım var mı?
Hayır. SDK, GIS uzmanları değil web geliştiricileri için tasarlanmıştır. Bir haritayı koordinatlarla ve bir yakınlaştırma seviyesiyle başlatırsınız, işaretçileri boylam/enlem çiftleriyle eklersiniz ve Coğrafi Kodlama API'sini düz metin ile çağırırsınız. Mekansal veritabanları veya GIS araçları gerekli değil.