প্রতিটি লজিস্টিক ড্যাশবোর্ড, রিয়েল এস্টেট তালিকা এবং খাদ্য বিতরণ অ্যাপের একটি জিনিস রয়েছে: একটি মানচিত্র। যদি আপনার ওয়েবসাইটের কাছে এখনও একটি না থাকে, তাহলে আপনি প্রসঙ্গটি টেবিলে ফেলে দিচ্ছেন। এমন প্রসঙ্গ যা ব্যবহারকারীদের অবস্থান, নৈকট্য এবং স্থানিক সম্পর্ক বুঝতে সাহায্য করে।
এই টিউটোরিয়ালটি আপনাকে যেকোনো 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://tiles.mapatlas.eu/styles/basic/style.json?key=YOUR_API_KEY',
center: [4.9041, 52.3676],
zoom: 12,
});
পৃষ্ঠা খুলুন এবং আপনি একটি ভেক্টর মানচিত্র দেখতে পাবেন যা আপনি টেনে, স্ক্রোল এবং নেভিগেট করতে চিমটি করতে পারেন। টাইলস MapAtlas সার্ভার থেকে চাহিদা অনুযায়ী লোড হয়, তাই কোনো ভারী আপফ্রন্ট ডাউনলোড নেই।
মানচিত্র শৈলী নির্বাচন করা
স্টাইল URL এ পাথ সেগমেন্ট স্ওয়াপ করে সম্পূর্ণ চেহারা পরিবর্তন করুন:
| শৈলী | URL পাথ | সেরা জন্য |
|---|---|---|
| Basic | /styles/basic/style.json | সাধারণ-উদ্দেশ্য অ্যাপ |
| Bright | /styles/bright/style.json | ডেটা ভিজ্যুয়ালাইজেশন ওভারলে |
| Dark | /styles/dark/style.json | ড্যাশবোর্ড, রাত মোড, বিশ্লেষণ |
দ্রুত জয়: কম আলোর পরিবেশে ব্যবহার করা অ্যাডমিন প্যানেল এবং সরঞ্জামগুলির জন্য ডার্ক স্টাইল ব্যবহার করুন। এটি চোখের চাপ কমায় এবং হিটম্যাপ এবং রুট লাইনের মতো ডেটা লেয়ারগুলি পটভূমির বিরুদ্ধে দৃশ্যত পপ করে।
ধাপ 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);
});
কর্মক্ষমতা নোট: একবার আপনি মোটামুটি 100 থেকে 200 চিহ্নিতকারী অতিক্রম করলে, জুম-আউট ভিউতে রেন্ডারিং লক্ষণীয়ভাবে ধীর হয়ে যায়। GeoJSON উৎস ক্লাস্টারিং সক্ষম করুন (SDK দ্বারা বাক্সের বাইরে সমর্থিত) কম জুম স্তরে কাছাকাছি চিহ্নিতকারীগুলি গ্রুপ করতে। ক্লাস্টারিং কনফিগারেশনের জন্য SDK ডক্স চেক করুন।
ধাপ 5: জিওকোডিং API দিয়ে ঠিকানা অনুসন্ধান যোগ করুন
জিওকোডিং API একটি টেক্সট ক্যোয়ারী (একটি রাস্তার ঠিকানা, শহরের নাম বা ল্যান্ডমার্ক) কে এমন সমন্বয়ে রূপান্তরিত করে যা আপনি উড়ে যেতে পারেন, চিহ্নিত করতে পারেন বা রুটিং অনুরোধে ফিড করতে পারেন।
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');
ফলাফল 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://tiles.mapatlas.eu/styles/basic/style.json?key=${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 প্লেসহোল্ডার মানচিত্র বান্ডেল ডাউনলোড করার সময় আপনার লেআউট স্থিতিশীল রাখে, cumulative layout shift (CLS) প্রতিরোধ করে, যা ব্যবহারকারীর অভিজ্ঞতা এবং Core Web Vitals উভয়ের জন্য গুরুত্বপূর্ণ।
উৎপাদন কর্মক্ষমতা চেকলিস্ট
শিপিং আগে, এই অপটিমাইজেশন মাধ্যমে চালিয়ে যান:
- ভাঁজের নিচে মানচিত্র অলসভাবে-লোড করুন। মানচিত্র শুধুমাত্র যখন এর কন্টেইনার ভিউতে স্ক্রোল করে তখন শুরু করতে
IntersectionObserverব্যবহার করুন। এটি প্রাথমিক পৃষ্ঠা লোড থেকে ~200 KB JavaScript পিছিয়ে রাখে। - ভেক্টর টাইলস দিয়ে লেগে থাকুন। ভেক্টর টাইলস যেকোনো স্ক্রিন ঘনত্বে পরিষ্কারভাবে মাপ করে, রাস্টার চিত্রগুলির চেয়ে দ্রুত লোড করে এবং অতিরিক্ত সার্ভার অনুরোধ ছাড়াই ক্লায়েন্ট-সাইড পুনঃস্টাইল করা যায়। MapAtlas ডিফল্টভাবে ভেক্টর টাইলস পরিবেশন করে।
- বড় চিহ্নিতকারী সেট ক্লাস্টার করুন। 100 থেকে 200 চিহ্নিতকারী অতিক্রম করা, জুম-আউট ভিউতে অক্লাস্টার্ড রেন্ডারিং লক্ষণীয় ফ্রেম ড্রপ সৃষ্টি করে। ক্লাস্টারিং এটি সম্পূর্ণরূপে সমাধান করে।
- আপনার API কী সার্ভার-সাইড রাখুন। কখনো একটি পাবলিক রিপোজিটরিতে কী কমিট করবেন না। পরিবেশ ভেরিয়েবল ব্যবহার করুন (
NEXT_PUBLIC_MAPATLAS_KEYNext.js এ) বা সংবেদনশীল অপারেশনের জন্য আপনার ব্যাকএন্ডের মাধ্যমে প্রক্সি অনুরোধ। - আঞ্চলিক অ্যাপের জন্য
maxBoundsসেট করুন। যদি আপনার ব্যবহারকারীরা শুধুমাত্র একটি ভূগোলের জন্য যত্নশীল হয়, ভিউপোর্ট সীমাবদ্ধ করুন যাতে সেই এলাকার বাইরে টাইলস কখনো অনুরোধ করা হয় না। কম নেটওয়ার্ক কল, দ্রুত লোড।
পরবর্তীতে কী তৈরি করতে হবে
আপনার কাছে একটি মানচিত্র রয়েছে যা রেন্ডার করে, চিহ্নিতকারী দেখায়, ঠিকানা অনুসন্ধান করে এবং React এর সাথে সংহত করে। এখানে যেতে হবে:
- Routing API: দুটি সমন্বয়ের মধ্যে ঘুরে-বাঁক নির্দেশনা অনুরোধ করুন। একটি রুট পলিলাইন, মোট দূরত্ব এবং অনুমানিত ভ্রমণ সময় ফেরত দেয়।
- Isochrone API: একটি বহুভুজ তৈরি করুন যা n মিনিটের মধ্যে পৌঁছানো যায় এমন প্রতিটি বিন্দু কভার করে। ডেলিভারি জোন, সেবা কভারেজ ম্যাপ এবং ক্যাচমেন্ট এলাকা বিশ্লেষণের জন্য ব্যবহৃত হয়।
- Matrix API: একটি একক অনুরোধে একাধিক উৎস এবং গন্তব্য মধ্যে ভ্রমণ সময় এবং দূরত্ব হিসাব করুন। ফ্লিট ডিসপ্যাচ এবং লজিস্টিক অপটিমাইজেশনের জন্য অপরিহার্য।
সম্পূর্ণ SDK রেফারেন্স, স্টাইল ডকুমেন্টেশন এবং API গাইড docs.mapatlas.xyz এ উপলব্ধ।
বারবার জিজ্ঞাসিত প্রশ্ন
আমি আমার ওয়েবসাইটে বিনামূল্যে ইন্টারেক্টিভ মানচিত্র যোগ করতে পারি?
হ্যাঁ। MapAtlas সাইন আপে কোনো ক্রেডিট কার্ড প্রয়োজন না বিনামূল্যে স্তর অফার করে। এটি ভেক্টর টাইল রেন্ডারিং, জিওকোডিং API এবং রুটিং API অন্তর্ভুক্ত করে। এটি উন্নয়ন এবং ছোট-স্কেল উৎপাদন ব্যবহারের জন্য যথেষ্ট।
আমি কীভাবে একটি React বা Next.js অ্যাপ্লিকেশনে একটি মানচিত্র এম্বেড করতে পারি?
মানচিত্র শুরু করা একটি useEffect হুকে মোড়ান যাতে এটি DOM মাউন্ট করার পরে চলে। Next.js এ, সার্ভার-সাইড রেন্ডারিং ত্রুটি এড়াতে ssr: false সহ dynamic() ব্যবহার করুন। উভয় পদ্ধতি এই টিউটোরিয়ালে কপি-পেস্ট উদাহরণ সহ কভার করা হয়েছে।
ভেক্টর টাইলস কি এবং আমি রাস্টারের উপর তাদের ব্যবহার করব কেন?
ভেক্টর টাইলস পূর্ব-রেন্ডার করা পিক্সেল চিত্রের পরিবর্তে গাণিতিক জ্যামিতি হিসাবে মানচিত্র বৈশিষ্ট্য (রাস্তা, ভবন, লেবেল) বর্ণনা করে। তারা যেকোনো রেজোলিউশনে তীক্ষ্ণভাবে স্কেল করে, রাস্টার চিত্রগুলির চেয়ে দ্রুত লোড করে এবং অতিরিক্ত সার্ভার রাউন্ডট্রিপ ছাড়াই ক্লায়েন্টে সম্পূর্ণভাবে পুনঃস্টাইল করা যায়।
আমি কর্মক্ষমতা হ্রাস করার আগে কতগুলি চিহ্নিতকারী যোগ করতে পারি?
রেন্ডারিং সাধারণত কম জুম স্তরে 100 থেকে 200 চিহ্নিতকারীর বাইরে হ্রাস পায়। ফিক্স ক্লাস্টারিং: MapAtlas SDK নেটিভভাবে GeoJSON উৎস ক্লাস্টারিং সমর্থন করে, কম জুম এ কাছাকাছি চিহ্নিতকারী গ্রুপিং এবং ব্যবহারকারী জুম করার সাথে সাথে সম্প্রসারিত।
MapAtlas ব্যবহার করার জন্য আমার GIS অভিজ্ঞতা প্রয়োজন?
না। SDK ওয়েব ডেভেলপারদের জন্য ডিজাইন করা হয়েছে, GIS বিশেষজ্ঞদের জন্য নয়। আপনি সমন্বয় এবং জুম স্তর দিয়ে একটি মানচিত্র শুরু করেন, দীর্ঘ/অক্ষাংশ জোড়া দিয়ে চিহ্নিতকারী যোগ করেন এবং সাধারণ পাঠ্য দিয়ে জিওকোডিং API কল করেন। কোনো স্থানিক ডেটাবেস বা GIS সরঞ্জাম প্রয়োজন।
