نحوه افزودن نقشه های تعاملی به وب سایت شما | آموزش JavaScript (2026) | MapAtlas Blog

هر پانل لجستیک، فهرست ملک و برنامه تحویل غذا یک چیز مشترک دارد: یک نقشه. اگر وب سایت شما هنوز یکی ندارد، زمینه را از دست می دهید. زمینه ای که به کاربران کمک می کند موقعیت، فاصله و روابط مکانی را در یک نگاه درک کنند.

این آموزش شما را از طریق فرآیند افزودن یک نقشه کاملاً تعاملی به هر پروژه JavaScript راهنمایی می کند. شما با یک نقشه رندر شده شروع می کنید، نشانگرها و پنجره های بازشو را اضافه می کنید، جستجوی آدرس را با API ژئوکدینگ متصل می کنید و با یک مؤلفه React آماده برای تولید که به صورت تمیز به Next.js کاهش می یابد به پایان می رسید.

در اینجا آنچه شما در پایان می سازید:

یک نقشه بردار زنده که با کلید API شما احراز اعتبار شده
نشانگرهای قابل کلیک با محتوای پنجره بازشو سفارشی
یک تابع جستجوی آدرس تقویت شده توسط ژئوکدینگ
یک مؤلفه React قابل استفاده مجدد با تمیز کردن مناسب و رسیدگی SSR برای Next.js
فهرست بررسی بهینه سازی عملکرد برای تولید

شرایط نیازمند

قبل از شروع، مطمئن شوید که موارد زیر را دارید:

یک کلید API MapAtlas (ثبت نام رایگان، بدون نیاز به کارت اعتباری). این کلید تک تمام سرویس های MapAtlas را احراز اعتبار می کند: کاشی ها، ژئوکدینگ و مسیریابی.
یک پروژه JavaScript. HTML ساده، React، Vue یا Svelte همه کار می کنند.
Node.js 18+ اگر از طریق npm نصب می کنید.

مرحله 1: SDK MapAtlas را نصب کنید

SDK را با npm به پروژه خود بکشید:

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>

مقدار پیکسل ثابت یا واحد viewport (100vh، 50vh) هر دو کار می کنند. ارتفاع های درصدی تنها زمانی کار می کنند که عنصر والدین نیز ارتفاع مشخصی داشته باشد.

مرحله 3: اولین نقشه تعاملی خود را رندر کنید

تنها سه خط پیکربندی: یک ظرف، یک URL سبک با کلید API شما و موقعیت شروع.

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 را در آن قرار دهید: آدرس ها، تصاویر کوچک، دکمه های فراخوان اقدام، هر آنچه رابط کاربری شما نیاز دارد.

رسم نشانگرهای متعدد از داده ها

اکثر برنامه های واقعی به بیش از یک پین نیاز دارند. روی یک آرایه حلقه بزنید و برای هر ورودی یک نشانگر ایجاد کنید:

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.maplatlas.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 خط بسازید: searchAddress را به رویداد input یک فیلد متن پیوند دهید، 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} />

رسیدگی به بازنمایی Server-Side در 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 استفاده کنید. این حدود 200 کیلوبایت JavaScript را از بار صفحه اولیه به تاخیر می اندازد.
با کاشی های بردار بماند. کاشی های بردار به صورت تمیز به هر چگالی صفحه نمایش مقیاس می کنند، از تصاویر شطرنجی سریع تر بارگذاری می کنند و بدون درخواست های سرویس گیر اضافی می تواند از جانب کلاینت سبک شود. MapAtlas بطور پیشفرض کاشی های بردار را سرو می کند.
مجموعه های بزرگ نشانگر را خوشه بندی کنید. فراتر از 100 تا 200 نشانگر، رندر غیر خوشه بندی شده در یک نمای کوچک منجر به افت قاب ملحوظ می شود. خوشه بندی این را کاملاً حل می کند.
کلید API خود را در سرویس گذاشته نگاه دارید. هرگز کلیدها را به یک مخزن عمومی فشار ندهید. برای عملیات حساس از متغیرهای محیط (NEXT_PUBLIC_MAPLATLAS_KEY در Next.js) استفاده کنید یا درخواست های پروکسی را از طریق backend خود صادر کنید.
maxBounds را برای برنامه های کاربردی منطقه ای تنظیم کنید. اگر کاربران شما فقط در یک جغرافیا اهتمام دارند، نمایش را محدود کنید تا کاشی های خارج از آن منطقه هرگز درخواست نشود. تماس های شبکه کمتر، بارگذاری سریع تر.

بعد چه می سازیم

شما یک نقشه دارید که رندر می شود، نشانگر ها را نشان می دهد، آدرسها را جستجو می کند و با React یکپارچه می شود. در اینجا از اینجا کجا بروید:

Routing API: جهت های قدم به قدم بین دو مختصات را درخواست کنید. یک پولیلن مسیر، فاصله کل و زمان سفر تخمینی را برمی گرداند.
Isochrone API: یک چند ضلعی ایجاد کنید که هر نقطه در دسترس را در n دقیقه پوشش دهد. برای مناطق تحویل، نقشه های پوشش سرویس و تجزیه و تحلیل منطقه استیعاب استفاده می شود.
Matrix API: زمان سفر و فاصله بین منابع متعدد و مقصد را در یک درخواست محاسبه کنید. برای تحویل ناوگان و بهینه سازی لجستیک ضروری.

مرجع SDK کامل، اسناد سبک و راهنمای API در docs.maplatlas.xyz موجود است.

سؤالات متداول

آیا می توانم نقشه های تعاملی را به وب سایت خود به صورت رایگان اضافه کنم؟

بله. MapAtlas یک سطح رایگان را بدون نیاز به کارت اعتباری در ثبت نام ارائه می دهد. این شامل رندر کاشی های بردار، API ژئوکدینگ و API مسیریابی است. این برای توسعه و استفاده تولید کوچک کافی است.

نقشه را چگونه در یک برنامه React یا Next.js تعبیه می کنید؟

شروع نقشه را در یک قلاب useEffect بپیچید تا بعد از نصب DOM اجرا شود. در Next.js، برای جلوگیری از خطاهای رندر سمت سرویس dynamic() را با ssr: false استفاده کنید. هر دو رویکرد با نمونه های کپی-پیست در این آموزش پوشش داده شده است.

کاشی های بردار چیست و چرا باید از آنها به جای رستر استفاده کنم؟

کاشی های بردار ویژگی های نقشه (جاده ها، ساختمان ها، برچسب ها) را به عنوان هندسه ریاضی به جای تصاویر پیکسل قبلا رندر شده توصیف می کنند. آنها به صورت تمیز به هر وضوح مقیاس می کنند، از تصاویر نقطی سریع تر بارگذاری می کنند و می توانند بدون جولان های سرویس گیر اضافی بصری بر روی کلاینت سبک شوند.

قبل از اینکه عملکرد بیفتد، می توانم چند نشانگر اضافه کنم؟

رندر معمولاً فراتر از 100 تا 200 نشانگر در سطح بزرگنمایی کم بدتر می شود. اصلاح خوشه بندی: SDK MapAtlas بطور محلی خوشه بندی منبع GeoJSON را پشتیبانی می کند، نشانگرهای نزدیک را در سطح بزرگنمایی کم گروه بندی می کند و در حالی که کاربر بزرگنمایی می کند آنها را گسترش می دهد.

آیا برای استفاده از MapAtlas به تجربه GIS نیاز دارم؟

نه. SDK برای توسعه دهندگان وب و نه متخصصین GIS طراحی شده است. شما یک نقشه را با مختصات و سطح بزرگنمایی شروع می کنید، نشانگر را با جفت طول/عرض شامل می کنید و API ژئوکدینگ را با متن ساده فراخوانی می کنید. پایگاه داده های مکانی یا ابزارهای GIS لازم نیست.