كيفية إضافة الخرائط التفاعلية إلى موقعك الإلكتروني | برنامج تعليمي JavaScript (2026) | MapAtlas Blog

كل لوحة تحكم لوجستية وقائمة العقارات وتطبيق توصيل الطعام لديها شيء واحد مشترك: خريطة. إذا كان موقعك الإلكتروني لا يملك واحدة حتى الآن، فأنت تتخلى عن السياق المهم. السياق الذي يساعد المستخدمين على فهم الموقع والقرب والعلاقات المكانية في لمحة واحدة.

يرشدك هذا البرنامج التعليمي خلال عملية إضافة خريطة تفاعلية بالكامل إلى أي مشروع JavaScript. ستبدأ برسم خريطة مرسومة، وتضيف العلامات والنوافذ المنبثقة، وتوصل البحث عن العناوين باستخدام API الجغرافي، وتنتهي بمكون React جاهز للإنتاج ينسجم بسهولة مع Next.js.

إليك ما ستبنيه في النهاية:

خريطة متجهة حية موثقة باستخدام مفتاح API الخاص بك
علامات قابلة للنقر مع محتوى نافذة منبثقة مخصصة
دالة بحث عناوين مدعومة بـ Geocoding
مكون React قابل لإعادة الاستخدام مع التنظيف الصحيح ومعالجة SSR للـ Next.js
قائمة تحقق لتحسينات الأداء للإنتاج

المتطلبات الأساسية

قبل البدء، تأكد من أن لديك:

مفتاح MapAtlas API (قم بالتسجيل مجانا, لا تحتاج إلى بطاقة ائتمان). هذا المفتاح الواحد يوثق كل خدمات MapAtlas: الملاط، والجغرافيا، والتوجيه.
مشروع JavaScript. HTML عادي أو React أو Vue أو Svelte كلها تعمل.
Node.js 18+ إذا كنت تثبت عبر npm.

الخطوة 1: قم بتثبيت MapAtlas SDK

سحب 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`	لوحات التحكم وضع الليل والتحليلات

الفوز السريع: استخدم نمط Dark لوحات الإدارة والأدوات المستخدمة في بيئات الإضاءة المنخفضة. إنه يقلل إجهاد العين ويجعل طبقات البيانات مثل خرائط الحرارة وخطوط المسارات تبرز بصريا على الخلفية.

الخطوة 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 Geocoding استعلاما نصيا (عنوان الشارع أو اسم المدينة أو المعلم) إلى إحداثيات يمكنك الانتقال إليها أو وضع علامة عليها أو إدخالها في طلب التوجيه.

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 سطرا: قم بإرفاق searchAddress بحدث input لحقل نص وأضف debounce بمدة 300ms، وستحصل على بحث خريطة بنمط الإكمال التلقائي بدون اعتماديات إضافية.

دمج الخرائط التفاعلية مع 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 Rendering للـ Next.js

يعتمد SDK الخريطة على واجهات برمجة تطبيقات المتصفح (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_MAPATLAS_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؟

لا. تم تصميم SDK لمطوري الويب وليس متخصصي جغرافيين. تقوم بتهيئة خريطة مع إحداثيات ومستوى تكبير وإضافة علامات مع أزواج الطول/العرض واستدعاء API الجغرافي مع نص عادي. لا تتطلب قواعد بيانات مكانية أو أدوات جغرافية.