إعداد وتخصيص خرائط Mapbox الأساسية في تطبيقات React Leaflet و Gatsby Starter Leaflet

Updated يونيو 18, 2026 8 min read

Aldawsari

دقائق القراءة: 8

تُعد الخرائط التفاعلية أداة قوية لتحليل البيانات الجغرافية وتصويرها، لكن غالبًا ما تكون أنماط الخرائط الافتراضية محدودة ولا تخدم احتياجات عرض بياناتك بشكل مثالي. هنا يأتي دور Mapbox، المنصة الرائدة التي تتيح لك إنشاء خرائط أساسية مخصصة بالكامل. في هذا الدليل، سنتعمق في كيفية دمج أنماط Mapbox المخصصة مع مكتبة React Leaflet الشهيرة، وكيفية تطبيقها ضمن مشروع Gatsby Starter Leaflet، مع التركيز على أفضل الممارسات الأمنية لضمان حماية مفاتيح الوصول الخاصة بك.

ما الذي سنبنيه في هذا الدليل؟

سنتناول خطوة بخطوة عملية إنشاء نمط Mapbox أساسي جديد ومخصص ضمن حسابك على Mapbox. بمجرد الانتهاء من ذلك، سنستخدم واجهة برمجة تطبيقات الخرائط (Map API) الخاصة بهم لإضافة هذا النمط الأساسي المخصص إلى تطبيق React Leaflet الخاص بنا. سنستعرض أيضًا كيفية دمج هذا النمط في مشروع Gatsby Starter Leaflet لإنشاء تطبيق خرائط متكامل.

لإنشاء خريطتنا، سنستخدم مشروع Leaflet Gatsby Starter الذي يوفر لك طريقة سهلة وسريعة لبدء تطبيق خرائط جديد. قبل أن نبدأ في إعداد هذا المشروع، سأوضح لك كيفية إضافة النمط المخصص باستخدام مكونات React Leaflet فقط، لضمان فهمك للأساسيات.

ما هي منصة Mapbox؟

Mapbox هي منصة خرائط رائدة تُمكّن عملائها من إنشاء حلول خرائط مخصصة بالكامل. تستفيد المنصة من مجموعة واسعة من واجهات برمجة التطبيقات (APIs) التي توفر قدرات قوية لبناء ميزات الخرائط المتنوعة. بدءًا من عرض الخرائط الأساسية وصولاً إلى تحليل البيانات الجغرافية المعقدة، تقدم Mapbox أدوات شاملة للمطورين والمصممين.

لأغراض هذا الدليل، سنركز على استخدام واجهة برمجة تطبيقات الخرائط (Map API) الخاصة بهم، وتحديدًا خدمة Static Tiles API، لعرض نمط خريطة مخصص سنقوم بإنشائه.

الجزء الأول: إنشاء نمط Mapbox مخصص

للحصول على المظهر والإحساس الذي نرغب فيه لخريطتنا، من الضروري أن يكون لدينا خريطة أساسية (basemap) تساعد في إبراز بياناتنا دون تشتيت الانتباه. بالإضافة إلى ذلك، قد يكون من الممتع أحيانًا امتلاك خريطة مخصصة تعكس هويتك أو تصميم تطبيقك.

إنشاء حساب Mapbox

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

إنشاء نمط مخصص جديد

إنشاء نمط جديد في Mapbox ليس بالأمر الصعب كما يبدو. بينما يمكن أن يصبح الأمر معقدًا للغاية إذا كنت ترغب في تصميم شيء فريد تمامًا، يمكننا البدء بنسخ أحد الأنماط الافتراضية لـ Mapbox. أولاً، توجه إلى لوحة تحكم Mapbox Studio بالنقر على رابط حسابك في الزاوية العلوية اليمنى بعد تسجيل الدخول.

بمجرد وصولنا إلى لوحة تحكم Studio، سنختار زر New Style (نمط جديد).

بعد النقر على الزر، ستظهر نافذة منبثقة تتيح لك اختيار قالب. يمكنك اختيار ما تريده هنا، ولكننا سنختار قالب Monochrome مع تباين Dark. بعد تحديد القالب الخاص بك، انقر على زر Customize (تخصيص).

والآن، تم نقلنا إلى واجهة المستخدم الخاصة بالتخصيص.

من هنا، يمكنك حقًا فعل ما يحلو لك. هناك العديد من الخيارات لتخصيص خريطتك. قد يكون الأمر معقدًا بعض الشيء للتعمق هنا، ولكن Mapbox يوفر بعض الموارد لمساعدتك على أن تصبح منتجًا.

إنشاء رمز Mapbox مميز (Token)

بمجرد أن تكون راضيًا عن نمطك الجديد وكل شيء منشور، نرغب في إنشاء رمز مميز (token) سنستخدمه لتوفير الوصول إلى خريطتنا. توجه إلى قسم Account (الحساب) في لوحة تحكم Mapbox.

يوفر لك Mapbox رمزًا “افتراضيًا” يمكنك استخدامه في تطبيقاتك. أنت حر في استخدامه، لكنني أوصي بإنشاء رمز جديد يمكنك تزويده باسم فريد، وبهذه الطريقة إذا تجاوزت المستوى المجاني من Mapbox، ستتمكن من تتبع استخدامك. بالإضافة إلى ذلك، من الأفضل الاحتفاظ برمز منفصل لكل تطبيق، وبهذه الطريقة يمكنك بسهولة تدوير مفتاح فردي، دون الحاجة إلى تحديث كل تطبيق يستخدمه. بمجرد النقر على Create a token (إنشاء رمز)، يمكنك إعداد المفتاح كما تريد، مع النطاقات والأذونات التي تختارها، ولكن لأغراضنا، يمكنك ترك جميع النطاقات العامة (Public scopes) محددة لخريطتنا، وهو ما يفعله Mapbox افتراضيًا.

تكوين نقطة النهاية المخصصة لدينا

لهذا الدليل، سنستخدم خدمة Static Tiles من Mapbox.

سيبدو عنوان URL لنقطة النهاية (endpoint) لدينا كما يلي:

https://api.mapbox.com/styles/v1/{username}/{style_id}/tiles/256/{z}/{x}/{y}@2x?access_token={access_token}

هناك بعض المعاملات هنا التي نحتاج إلى فهمها:

username: سيكون هذا هو اسم المستخدم الخاص بحسابك على Mapbox.
style_id: سيكون هذا هو معرف النمط الذي أنشأته سابقًا.
z, x, y: هذه معاملات يتم استبدالها برمجيًا بواسطة Leaflet، لذا نرغب في تركها كما هي.
access_token: هذا هو مفتاح Mapbox الذي أنشأته أعلاه.

للعثور على اسم المستخدم ومعرف النمط الخاص بك، يمكننا استخدام عنوان URL للنمط (Style URL) لنمط Mapbox الجديد للحصول على تلك القيم.

في مثالي، يبدو عنوان URL لنمطي كما يلي:

mapbox://styles/colbyfayock/ck8lryjfq0jdo1ip9ctmuhc6p

حيث colbyfayock هو اسم المستخدم الخاص بي و ck8lryjfq0jdo1ip9ctmuhc6p هو معرف النمط الخاص بي. وبمجرد تحديث معاملات نقطة النهاية الخاصة بي، سيبدو عنوان URL النهائي لـ tilepoint كما يلي:

https://api.mapbox.com/styles/v1/colbyfayock/ck8lryjfq0jdo1ip9ctmuhc6p/tiles/256/{z}/{x}/{y}@2x?access_token=MYACCESSTOKEN

الجزء الثاني: إضافة طبقة تجانب مخصصة (TileLayer) إلى React Leaflet

عند بناء خريطة باستخدام React Leaflet، سيكون المكون الرئيسي هو <Map> الذي يغلف التطبيق بأكمله. هذا هو ما يقوم بتهيئة مثيل الخريطة لـ Leaflet. لأغراضنا هنا، سنستخدم المثال الموجود على الصفحة الرئيسية لـ React Leaflet كنقطة بداية لنا.

مكون TileLayer في React Leaflet

داخل مكون <Map>، تقوم بتضمين مكون <TileLayer>، الذي يحدد صور العالم التي تستند إليها خريطتك. يستخدم المثال الموجود على الصفحة الرئيسية لـ React Leaflet إصدارًا عامًا من OpenStreetMap كـ TileLayer الخاص بهم، وهو مشروع خرائط مفتوح المصدر تم إنشاؤه وتحديثه بواسطة أشخاص من جميع أنحاء العالم.

<Map center={position} zoom={13}>
  <TileLayer
    url="https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png"
    attribution="&copy; <a href=&quot;http://osm.org/copyright&quot;>OpenStreetMap</a> contributors"
  />
</Map>

يمنحك هذا خريطة أساسية، لكننا نريد استبدالها بـ Mapbox حتى نتمكن من إعداد مظهر وإحساس مخصص لخريطتنا.

طبقة تجانب Mapbox مخصصة

لإضافة نمطنا المخصص، سنحتاج إلى تحديث خاصيتي url و attribution لمكون TileLayer. بالنسبة لـ url، سيكون ببساطة هو عنوان نقطة النهاية المخصصة التي أنشأناها سابقًا. أما بالنسبة لـ attribution، فيجب أن ننسب الفضل إلى Mapbox كمزود للخدمة. بعد التحديث، سيبدو الكود الخاص بنا كالتالي:

<Map center={position} zoom={13}>
  <TileLayer
    url="https://api.mapbox.com/styles/v1/colbyfayock/ck8lryjfq0jdo1ip9ctmuhc6p/tiles/256/{z}/{x}/{y}@2x?access_token=MYACCESSTOKEN"
    attribution="Map data &copy; <a href=&quot;https://www.openstreetmap.org/&quot;>OpenStreetMap</a> contributors, <a href=&quot;https://creativecommons.org/licenses/by-sa/2.0/&quot;>CC-BY-SA</a>, Imagery &copy; <a href=&quot;https://www.mapbox.com/&quot;>Mapbox</a>"
  />
</Map>

وبمجرد فتح الخريطة، يجب أن نرى نمط الخريطة الأساسي الجديد الخاص بنا!

ملاحظة: لضمان أمان مفتاح Mapbox الخاص بك، يُنصح بتخزينه في ملف .env.development.local في جذر مشروعك كمتغير بيئة، مثل REACT_APP_MAPBOX_KEY.

الجزء الثالث: إضافة خريطة أساسية مخصصة إلى Gatsby Starter Leaflet

لقد كتبت بعض المقالات الأخرى حول كيفية البدء باستخدام Leaflet Gatsby Starter، ولكن لهذا الجزء، سنحتاج إلى تطبيق أساسي جاهز يمكننا استخدامه لتغيير نقطة نهاية TileLayer الخاصة بنا.

إعداد تطبيق React Leaflet Gatsby الخاص بنا

للبدء، راجع التعليمات الموجودة على مستودع GitHub الخاص بـ Starter: https://github.com/colbyfayock/gatsby-starter-leaflet. بمجرد أن تكون جاهزًا، يجب أن يكون لديك تطبيق خرائط أساسي جاهز للعمل!

تكوين خدمة Mapbox الخاصة بنا

الخطوة الأولى التي سنرغب في القيام بها هي إضافة Mapbox كخدمة في ملف src/data/map-services.js الخاص بنا. باستخدام عنوان URL لنقطة النهاية المخصصة التي أنشأناها في الجزء الأول، دعنا ننشئ كائنًا جديدًا باسم Mapbox، ومع خاصيتي url و attribution المشابهتين لما فعلناه في الجزء الثاني.

export const mapServices = [
  {
    name: 'OpenStreetMap',
    attribution: '&copy; <a href="http://osm.org/copyright">OpenStreetMap</a> contributors',
    url: 'https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png'
  },
  {
    name: 'Mapbox',
    attribution: 'Map data &copy; <a href=&quot;https://www.openstreetmap.org/&quot;>OpenStreetMap</a> contributors, <a href=&quot;https://creativecommons.org/licenses/by-sa/20/&quot;>CC-BY-SA</a>, Imagery &copy; <a href=&quot;https://www.mapbox.com/&quot;>Mapbox</a>',
    url: `https://api.mapbox.com/styles/v1/colbyfayock/ck8c2foj72lqk1jnug0g2haw0/tiles/256/{z}/{x}/{y}@2x?access_token=MY_ACCESS_TOKEN`
  }
];

استخدام خدمة خريطة Mapbox الخاصة بنا

بمجرد إعداد خدمة Mapbox الخاصة بك، كل ما تبقى هو فتح ملف src/pages/index.js، والعثور على تعريف كائن mapSettings، وتحديث خاصية defaultBaseMap إلى Mapbox.

const mapSettings = {
  center: CENTER,
  defaultBaseMap: 'Mapbox',
  zoom: DEFAULT_ZOOM,
  mapEffect
};

احفظ هذا التغيير، وحدث الخريطة في متصفحك، ويجب أن ترى الآن نمط الخريطة الأساسي المخصص الخاص بك!

ملاحظة: لضمان أمان مفتاح Mapbox الخاص بك، يُنصح بتخزينه في ملف .env.development في جذر مشروعك كمتغير بيئة، مثل GATSBY_MAPBOX_KEY.

تأمين مفتاح Mapbox الخاص بك

متغيرات البيئة (Environment Variables)

يُعد استخدام متغيرات البيئة (Environment variables) جزءًا أساسيًا من معظم عمليات التطوير التي تستخدم مفاتيح فردية. هذه المتغيرات هي إعدادات لا تُخزن مباشرةً في الكود المصدري. هذا مهم للغاية لأنه يمنع رفع مفتاحك إلى مستودع الكود (code repository)، وهو أمر سيء من منظور أمني. كما أنه يتيح لك توفير مفاتيح مختلفة لبيئات مختلفة (مثل التطوير والإنتاج). عند إنشاء مفاتيحك، ضع هذا في الاعتبار لتوفير الوقت والجهد على المدى الطويل.

تقييد مفتاح Mapbox الخاص بك

عند إنشاء أو تعديل مفتاح Mapbox، تسمح لك الإعدادات بتحديد عناوين URL التي يُسمح لمفتاحك بالوصول إليها فقط. على الرغم من أن Mapbox يقدم طبقة مجانية سخية، إلا أنه من الحكمة تقييد استخدام مفتاحك على عناوين URL التي تستخدمها بالفعل. يمكنك إنشاء مفاتيح متعددة: واحد للاستخدام العام على موقعك الإلكتروني، وآخر لتطويرك المحلي. هذا مفيد، على سبيل المثال، إذا كان لديك مفتاح لن يتم استخدامه علنًا لأغراض التطوير، ثم مفتاح آخر تنشره مع تطبيقك، والذي يمكن تقييده على عنوان URL هذا فقط. إذا تمكن شخص ما من الحصول على مفتاحك، فقد يستخدمه في موقعه الخاص ويستهلك كل حصتك المجانية، مما قد يؤدي إلى فواتير غير متوقعة!

هل تريد معرفة المزيد عن الخرائط؟

إذا كنت مهتمًا بتعميق معرفتك في مجال تطوير الخرائط، فهناك العديد من الموارد والمواضيع التي يمكنك استكشافها، مثل:

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

الخلاصة التقنية

تُظهر هذه المقالة بوضوح قوة ومرونة منصة Mapbox عند دمجها مع مكتبات React Leaflet و Gatsby. إن القدرة على تخصيص الخرائط الأساسية لا يضيف فقط لمسة جمالية فريدة للتطبيقات، بل يعزز أيضًا قابلية قراءة البيانات وتقديمها بشكل فعال للمستخدمين. الالتزام بالممارسات الأمنية، مثل استخدام متغيرات البيئة وتقييد مفاتيح الوصول، أمر بالغ الأهمية لحماية المشاريع والموارد. هذا النهج المتكامل يُمكّن المطورين من بناء تجارب خرائط غنية وآمنة ومحسّنة للأداء، مما يفتح آفاقًا واسعة لإنشاء تطبيقات ويب جغرافية مبتكرة وذات قيمة مضافة.