अपनी वेबसाइट में इंटरेक्टिव मानचित्र कैसे जोड़ें | JavaScript

हर लॉजिस्टिक्स डैशबोर्ड, रीयल एस्टेट लिस्टिंग, और खाद्य वितरण ऐप का एक समान बात है: एक मानचित्र। यदि आपकी वेबसाइट में अभी तक कोई मानचित्र नहीं है, तो आप महत्वपूर्ण जानकारी खो रहे हैं। वह जानकारी जो उपयोगकर्ताओं को स्थान, निकटता, और स्थानिक संबंधों को एक नज़र में समझने में मदद करती है।

यह ट्यूटोरियल आपको किसी भी JavaScript प्रोजेक्ट में पूरी तरह से इंटरेक्टिव मानचित्र जोड़ने के तरीके के बारे में बताता है। आप एक रेंडर किए गए मानचित्र से शुरुआत करेंगे, मार्कर और पॉपअप जोड़ेंगे, जियोकोडिंग API के साथ पता खोज को कनेक्ट करेंगे, और एक उत्पादन-तैयार React घटक के साथ समाप्त करेंगे जो Next.js में स्वच्छता से गिरता है।

यहाँ वह है जो आप अंत तक बनाएंगे:

• आपकी API कुंजी के साथ प्रमाणित एक लाइव वेक्टर मानचित्र
• कस्टम पॉपअप सामग्री के साथ क्लिक करने योग्य मार्कर
• जियोकोडिंग-संचालित पता खोज कार्य
• उचित सफाई और Next.js SSR हैंडलिंग के साथ पुनः प्रयोज्य React घटक
• उत्पादन के लिए प्रदर्शन अनुकूलन चेकलिस्ट

पूर्वापेक्षाएँ

शुरुआत से पहले, सुनिश्चित करें कि आपके पास है:

• MapAtlas API कुंजी (मुफ्त साइन अप करें, कोई क्रेडिट कार्ड की आवश्यकता नहीं)। यह एकल कुंजी हर MapAtlas सेवा को प्रमाणित करती है: टाइलें, जियोकोडिंग, और रूटिंग।
• एक JavaScript प्रोजेक्ट। सादा HTML, React, Vue, या Svelte सभी काम करते हैं।
• Node.js 18+ (यदि npm के माध्यम से स्थापित कर रहे हैं)।

चरण 1: MapAtlas SDK स्थापित करें

npm के साथ SDK को अपने प्रोजेक्ट में खींचें:

npm install @mapmetrics/mapmetrics-gl

यदि आप एक सादा HTML पृष्ठ के साथ काम कर रहे हैं, तो CDN लिंक को अपने <head> में डालें:

<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 आयात को छोड़ें मत। इसके बिना, मानचित्र नियंत्रण और पॉपअप बिना शैली के रेंडर होते हैं। कार्यात्मक, लेकिन दृश्यमान रूप से टूटा हुआ।

चरण 2: एक मानचित्र कंटेनर बनाएं

SDK जिस किसी भी तत्व को आप इंगित करते हैं उसे भरता है, इसलिए आपको एक स्पष्ट ऊंचाई के साथ <div> की आवश्यकता है। यह सबसे आम सेटअप गलती है: यदि कंटेनर में height: 0 है, तो मानचित्र प्रारंभ होता है लेकिन अदृश्य रहता है।

<div id="map" style="width: 100%; height: 500px;"></div>

एक निश्चित पिक्सेल मान या व्यूपोर्ट इकाई (100vh, 50vh) दोनों काम करते हैं। प्रतिशत ऊंचाई तभी काम करती है जब माता-पिता के तत्व के पास भी परिभाषित ऊंचाई हो।

चरण 3: अपना पहला इंटरेक्टिव मानचित्र रेंडर करें

केवल तीन पंक्तियों का कॉन्फ़िगरेशन काफी है: एक कंटेनर, आपकी API कुंजी के साथ एक शैली URL, और एक शुरुआती स्थिति।

import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';

const map = new mapmetricsgl.Map({
  container: 'map',
  style: 'https://gateway.mapmetrics-atlas.net/styles/?fileName=YOUR_STYLE_ID/style.json&token=YOUR_API_KEY',
  center: [4.9041, 52.3676],
  zoom: 12,
});

पृष्ठ खोलें और आप एक वेक्टर मानचित्र देखेंगे जिसे आप खींच सकते हैं, स्क्रॉल कर सकते हैं, और नेविगेट करने के लिए चुटकी ले सकते हैं। टाइलें MapAtlas सर्वर से आवश्यकता के अनुसार लोड होती हैं, इसलिए कोई भारी प्रारंभिक डाउनलोड नहीं है।

एक मानचित्र शैली चुनें

मानचित्र शैलियाँ आपके खाते में रहती हैं। MapMetrics पोर्टल में Styles खोलें, कोई शैली बनाएँ या उसे अनुकूलित करें, सेव करें और उसका Style URL कॉपी करें। इस URL में आपका token पहले से शामिल होता है, इसलिए यह सीधे style विकल्प में जाता है। हर ज़रूरी रूप के लिए एक शैली रखें, जैसे सामान्य ऐप्स के लिए हल्की शैली और डैशबोर्ड के लिए गहरी शैली, और map.setStyle() से उनके बीच बदलें।

त्वरित जीत: प्रशासनिक पैनलों और कम रोशनी वाले वातावरण में उपयोग किए जाने वाले उपकरणों के लिए गहरी शैली का उपयोग करें। कम रोशनी वाले कमरों में कई उपयोगकर्ता इसे पसंद करते हैं, और यह हीटमैप और मार्ग लाइनों जैसी डेटा परतों को पृष्ठभूमि के विरुद्ध दृश्यमान रूप से पॉप करता है।

चरण 4: अपने मानचित्र में मार्कर और पॉपअप जोड़ें

बिना मार्कर के एक मानचित्र सिर्फ एक पृष्ठभूमि छवि है। मार्कर एक स्थिर दृश्य को कुछ ऐसे में बदल देते हैं जिसके साथ उपयोगकर्ता बातचीत कर सकते हैं।

एक पॉपअप के साथ एकल मार्कर

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

मार्कर पर क्लिक करें और पॉपअप खुल जाता है। आप अंदर कोई भी HTML रख सकते हैं: पते, थंबनेल, CTA बटन, कुछ भी जो आपके UI को बुलाता है।

डेटा से कई मार्कर की साजिश रचें

अधिकांश वास्तविक-दुनिया के ऐप को एक से अधिक पिन की आवश्यकता होती है। एक सरणी पर लूप करें और प्रत्येक प्रविष्टि के लिए एक मार्कर बनाएं:

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

प्रदर्शन नोट: HTML मार्कर DOM तत्व होते हैं, इसलिए कुछ सौ मार्कर ही ज़ूम आउट दृश्य में मानचित्र को धीमा कर देते हैं। उस स्थिति में बिंदुओं को क्लस्टरिंग वाले GeoJSON स्रोत में ले जाएँ (SDK इसे बिना अतिरिक्त सेटअप के समर्थित करता है) और उन्हें एक परत के रूप में बनाएँ। क्लस्टरिंग कॉन्फ़िगरेशन के लिए SDK दस्तावेज़ देखें।

चरण 5: जियोकोडिंग API के साथ पता खोज जोड़ें

जियोकोडिंग API एक पाठ क्वेरी (एक सड़क पता, शहर का नाम, या स्थल) को निर्देशांक में बदल देता है जिसे आप पैन कर सकते हैं, चिह्नित कर सकते हैं, या रूटिंग अनुरोध में डाल सकते हैं।

async function searchAddress(query) {
  const url = new URL('https://gateway.mapmetrics-atlas.net/forward-geocode/');
  url.searchParams.set('text', query);
  url.searchParams.set('token', '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');

परिणाम GeoJSON विशेषताओं के रूप में वापस आते हैं, इसलिए वे किसी भी GeoJSON-संगत परत, डेटा तालिका, या डाउनस्ट्रीम API कॉल में सीधे प्लग करते हैं।

30 पंक्तियों के तहत एक लाइव खोज पट्टी बनाएं: टेक्स्ट फ़ील्ड के input इवेंट को searchAddress संलग्न करें, इसे 300ms से debounce करें, और आपके पास कोई अतिरिक्त निर्भरता के बिना ऑटोकंपलीट-शैली की मानचित्र खोज है।

React के साथ इंटरेक्टिव मानचित्र को एकीकृत करना

एक पुनः प्रयोज्य मानचित्र घटक

मानचित्र आरंभीकरण को useEffect में लपेटें ताकि यह DOM माउंट के बाद चले, और अनमाउंट पर मेमोरी रिसाव को रोकने के लिए एक सफाई फ़ंक्शन वापस करें:

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://gateway.mapmetrics-atlas.net/styles/?fileName=YOUR_STYLE_ID/style.json&token=${apiKey}`,
      center, zoom,
    });
    return () => map.remove();
  }, [apiKey]);
  return <div ref={containerRef} style={{ width: '100%', height: '500px' }} />;
}

इसे अपने घटक पेड़ के कहीं भी उपयोग करें:

<MapAtlasMap apiKey={process.env.NEXT_PUBLIC_MAPATLAS_KEY} center={[4.9041, 52.3676]} zoom={13} />

Next.js सर्वर-साइड रेंडरिंग को संभालना

मानचित्र SDK ब्राउज़र API पर निर्भर करता है (window, document) जो SSR के दौरान मौजूद नहीं हैं। SSR अक्षम के साथ घटक को गतिशील रूप से आयात करें:

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 प्लेसहोल्डर मानचित्र बंडल डाउनलोड होने के समय लेआउट को स्थिर रखता है, संचयी लेआउट शिफ्ट (CLS) को रोकता है, जो उपयोगकर्ता अनुभव और Core Web Vitals दोनों के लिए महत्वपूर्ण है।

उत्पादन प्रदर्शन चेकलिस्ट

शिप करने से पहले, इन अनुकूलनों के माध्यम से चलाएं:

• फ़ोल्ड के नीचे मानचित्र को आलसी-लोड करें। IntersectionObserver का उपयोग करें केवल तभी मानचित्र को आरंभ करने के लिए जब इसका कंटेनर दृश्य में स्क्रॉल हो जाए। यह प्रारंभिक पृष्ठ लोड से लगभग 250 KB संपीड़ित JavaScript को स्थगित करता है।
• वेक्टर टाइलों पर टिके रहें। वेक्टर टाइलें किसी भी स्क्रीन घनत्व को स्वच्छ रूप से स्केल करती हैं, ज़ूम करने पर कम अनुरोध भेजती हैं, और अतिरिक्त सर्वर अनुरोधों के बिना क्लाइंट-साइड को पूरी तरह से पुनः स्टाइल कर सकती हैं। MapAtlas डिफ़ॉल्ट रूप से वेक्टर टाइलें प्रदान करता है।
• बड़े मार्कर सेट को क्लस्टर करें। ज़ूम आउट दृश्य में कुछ सौ HTML मार्कर ध्यान देने योग्य फ्रेम ड्रॉप का कारण बनते हैं। क्लस्टर की गई GeoJSON परत इससे बचाती है।
• ब्राउज़र कुंजियों को सीमित करें। ब्राउज़र में इस्तेमाल होने वाली कुंजी, जिसमें NEXT_PUBLIC_ पर्यावरण चर में रखी कुंजी भी शामिल है, DevTools खोलने वाले किसी भी व्यक्ति को दिखती है। कुंजियों को कभी किसी सार्वजनिक रिपॉजिटरी में कमिट न करें, पोर्टल में ब्राउज़र कुंजियों को अपने ही डोमेन तक सीमित करें, और संवेदनशील संचालन के लिए अनुरोधों को अपने बैकएंड के माध्यम से प्रॉक्सी करें।
• क्षेत्रीय ऐप के लिए maxBounds सेट करें। यदि आपके उपयोगकर्ता केवल एक भूगोल की परवाह करते हैं, तो दृश्यपोर्ट को प्रतिबंधित करें ताकि उस क्षेत्र के बाहर की टाइलें कभी अनुरोध न की जाएं। कम नेटवर्क कॉल, तेजी से लोड।

आगे क्या बनाएं

आपके पास एक मानचित्र है जो रेंडर करता है, मार्कर दिखाता है, पते खोजता है, और React के साथ एकीकृत होता है। यहाँ से कहाँ जाना है:

• रूटिंग API: दो निर्देशांक के बीच टर्न-दर-टर्न निर्देश अनुरोध करें। मार्ग पॉलीलाइन, कुल दूरी, और अनुमानित यात्रा समय लौटाता है।
• Isochrone API: n मिनट के भीतर पहुंचने योग्य हर बिंदु को कवर करने वाला एक बहुभुज बनाएं। डिलीवरी ज़ोन, सेवा कवरेज मानचित्र, और जलग्रहण क्षेत्र विश्लेषण के लिए उपयोग किया जाता है।
• मैट्रिक्स API: एक एकल अनुरोध में कई मूल और गंतव्यों के बीच यात्रा समय और दूरी की गणना करें। फ्लीट डिस्पैच और रसद अनुकूलन के लिए आवश्यक है।

पूर्ण SDK संदर्भ, शैली दस्तावेज़, और API गाइड docs.mapatlas.xyz पर उपलब्ध हैं।

अक्सर पूछे जाने वाले प्रश्न

क्या मैं अपनी वेबसाइट पर इंटरेक्टिव मानचित्र मुफ्त में जोड़ सकता हूँ?

हाँ। MapAtlas एक मुफ्त स्तर प्रदान करता है जिसमें साइन-अप के समय कोई क्रेडिट कार्ड की आवश्यकता नहीं है। इसमें वेक्टर टाइल रेंडरिंग, जियोकोडिंग API, और रूटिंग API शामिल हैं। यह विकास और छोटे पैमाने पर उत्पादन उपयोग के लिए पर्याप्त है।

मैं React या Next.js ऐप में मानचित्र कैसे एम्बेड करूँ?

मानचित्र आरंभीकरण को useEffect हुक में लपेटें ताकि यह DOM माउंट के बाद चले। Next.js में, सर्वर-साइड रेंडरिंग त्रुटियों से बचने के लिए dynamic() को ssr: false के साथ उपयोग करें। दोनों दृष्टिकोण इस ट्यूटोरियल में कॉपी-पेस्ट उदाहरणों के साथ कवर किए गए हैं।

वेक्टर टाइलें क्या हैं, और मुझे रैस्टर के बजाय उनका उपयोग क्यों करना चाहिए?

वेक्टर टाइलें मानचित्र सुविधाओं (सड़कें, इमारतें, लेबल) को पूर्व-रेंडर किए गए पिक्सेल छवियों के बजाय गणितीय ज्यामिति के रूप में वर्णित करती हैं। वे किसी भी रिज़ॉल्यूशन को तेजी से स्केल करते हैं, ज़ूम करने पर कम डाउनलोड माँगते हैं, और अतिरिक्त सर्वर राउंड-ट्रिप के बिना क्लाइंट-साइड पूरी तरह से पुनः स्टाइल कर सकते हैं।

प्रदर्शन गिरने से पहले मैं कितने मार्कर जोड़ सकता हूँ?

कम ज़ूम स्तरों पर कुछ सौ HTML मार्कर तक पहुँचते ही रेंडरिंग आमतौर पर धीमी पड़ने लगती है। समाधान क्लस्टरिंग है: MapAtlas SDK GeoJSON स्रोत क्लस्टरिंग को मूल रूप से समर्थन करता है, कम ज़ूम स्तरों पर निकटवर्ती मार्कर को समूहित करता है और जब उपयोगकर्ता ज़ूम करता है तो उन्हें विस्तारित करता है।

क्या मुझे MapAtlas का उपयोग करने के लिए GIS अनुभव की आवश्यकता है?

नहीं। SDK को GIS विशेषज्ञों के बजाय वेब डेवलपर्स के लिए डिज़ाइन किया गया है। आप निर्देशांक और ज़ूम स्तर के साथ एक मानचित्र प्रारंभ करते हैं, देशांतर/अक्षांश जोड़ी के साथ मार्कर जोड़ते हैं, और जियोकोडिंग API को साधारण पाठ के साथ कॉल करते हैं। कोई स्थानिक डेटाबेस या GIS उपकरण की आवश्यकता नहीं है।