إضافة خريطة إلى موقعك الإلكتروني (JavaScript)

1. قبل البدء

في هذا الدرس التطبيقي حول الترميز، ستتعرّف على كل ما تحتاج إليه للبدء في استخدام "منصة خرائط Google" للويب. ستتعلم جميع الأساسيات، بدءًا من الإعداد وحتى تحميل واجهة برمجة تطبيقات JavaScript للخرائط، وعرض خريطتك الأولى، والعمل باستخدام العلامات وجمع العلامات، والرسم على الخريطة، والتعامل مع تفاعل المستخدم.

العناصر التي سيتم إنشاؤها

في هذا الدرس التطبيقي حول الترميز، يمكنك إنشاء تطبيق ويب بسيط ينفّذ ما يلي:

• لتحميل واجهة برمجة تطبيقات JavaScript للخرائط
• يعرض خريطة تتمركز في سيدني، أستراليا
• عرض محدّدات المواقع المخصصة للمعالم السياحية الشهيرة في سيدني
• تنفيذ تجميع العلامات
• تفعِّل هذه السياسة تفاعل المستخدم الذي أحدثه ويرسم دائرة على الخريطة عند النقر على علامة.

ما ستتعرَّف عليه

• بدء استخدام "منصة خرائط Google"
• تحميل واجهة برمجة تطبيقات JavaScript للخرائط ديناميكيًا من رمز JavaScript
• جارٍ تحميل خريطة
• استخدام العلامات والعلامات المخصصة وتجميع العلامات
• العمل مع نظام أحداث واجهة برمجة تطبيقات JavaScript لتوفير تفاعل المستخدم
• التحكم في الخريطة ديناميكيًا
• الرسم على الخريطة

2. المتطلّبات الأساسية

ستحتاج إلى التعرّف على العناصر أدناه لإكمال هذا الدرس التطبيقي حول الترميز. إذا كنت معتادًا على العمل باستخدام منصة خرائط Google، انتقل إلى الدرس التطبيقي حول الترميز.

منتجات "منصة خرائط Google" المطلوبة

في هذا الدرس التطبيقي حول الترميز، ستستخدِم منتجات "منصة خرائط Google" التالية:

• واجهة برمجة تطبيقات JavaScript للخرائط
• مكتبة تجميع علامات مفتوحة المصدر MarkerClustererPlus

المتطلبات الأخرى لهذا الدرس التطبيقي حول الترميز

لإكمال هذا الدرس التطبيقي حول الترميز، ستحتاج إلى الحسابات والخدمات والأدوات التالية:

• حساب Google Cloud Platform تم تفعيل الفوترة به
• مفتاح API لمنصة "خرائط Google" مع تفعيل واجهة برمجة تطبيقات JavaScript ل"خرائط Google"
• معرفة أساسية بلغة JavaScript وHTML وCSS
• تم تثبيت Node.js على جهاز الكمبيوتر
• محرِّر نصوص أو IDE من اختيارك

بدء استخدام "منصة خرائط Google"

إذا لم يسبق لك استخدام "منصة خرائط Google"، يمكنك اتّباع دليل بدء استخدام "منصة خرائط Google" أو مشاهدة "البدء في استخدام قائمة تشغيل منصة خرائط Google" لإكمال الخطوات التالية:

1. أنشئ حساب فوترة.
2. أنشئ مشروعًا.
3. فعِّل واجهات برمجة تطبيقات ومنصة SDK لمنصة "خرائط Google" (المُدرَجة في القسم السابق).
4. أنشئ مفتاح واجهة برمجة تطبيقات.

3- الإعداد

إعداد "منصة خرائط Google"

إذا لم يكن لديك حساب على Google Cloud Platform ومشروع تم تفعيل الفوترة فيه، يُرجى الاطّلاع على دليل بدء استخدام "منصة خرائط Google" لإنشاء حساب فوترة ومشروع.

1. في Cloud Console، انقر على القائمة المنسدلة للمشروع واختَر المشروع الذي تريد استخدامه لهذا الدرس التطبيقي.

2. فعِّل واجهات برمجة تطبيقات ومنصة SDK لمنصة "خرائط Google" المطلوبة لهذا الدرس التطبيقي في Google Cloud Marketplace. ولإجراء ذلك، اتّبِع الخطوات الواردة في هذا الفيديو أو هذه المستندات.
3. يمكنك إنشاء مفتاح واجهة برمجة تطبيقات في صفحة بيانات الاعتماد في Cloud Console. يمكنك اتّباع الخطوات الواردة في هذا الفيديو أو هذه المستندات. تتطلب جميع الطلبات إلى "منصة خرائط Google" مفتاح واجهة برمجة تطبيقات.

إعداد Node.js

في حال عدم توفّره، انتقِل إلى https://nodejs.org/ لتنزيل وقت تشغيل Node.js وتثبيته على جهاز الكمبيوتر.

يتوفّر برنامج Node.js مع مدير حزمة npm، والذي تحتاج إلى تثبيت تبعيات لهذا الدرس التطبيقي حول الترميز.

إعداد نموذج إجراء المبتدئين

قبل بدء هذا الدرس التطبيقي، يُرجى اتّباع الخطوات التالية لتنزيل نموذج المشروع للمبتدئين، بالإضافة إلى رمز الحلّ الكامل:

1. نزِّل اختبار GitHub أو تشعّبه لهذا الدرس التطبيقي على https://github.com/googlecodelabs/maps-platform-101-js.

يقع مشروع المبتدئين في الدليل /starter ويشمل بنية الملف الأساسية التي تحتاجها لإكمال الدرس التطبيقي حول الترميز. ستجد كل ما تحتاج إليه للعمل في دليل /starter/src. 2. بعد تنزيل مشروع التفعيل، يمكنك تشغيل npm install في الدليل /starter. يؤدي ذلك إلى تثبيت جميع التبعيات المطلوبة المدرجة في package.json. 3- بعد تثبيت تبعيات الأجهزة، يمكنك تشغيل npm start في الدليل.

تم إعداد مشروع المبتدئين لك لاستخدام webpack-dev-server، الذي يجمع ويشغِّل الرمز الذي تكتبه محليًا. وستتم أيضًا إعادة تحميل تطبيقك في المتصفح تلقائيًا في أي وقت تجري فيه تغييرات على الرمز.

إذا كنت تريد عرض رمز الحل بالكامل، يمكنك إكمال خطوات الإعداد أعلاه في دليل /solution.

4. تحميل واجهة برمجة تطبيقات JavaScript للخرائط

قبل البدء، يُرجى التأكّد من اتّباع الخطوات في الإعداد. هل اكتملت العملية؟ حسنًا، حان الوقت لإنشاء أول تطبيق ويب لك باستخدام Google Maps Platform.

أساس استخدام "منصة خرائط Google" للويب هو واجهة برمجة تطبيقات JavaScript لـ "خرائط Google". توفر واجهة برمجة التطبيقات هذه واجهة JavaScript لاستخدام جميع ميزات منصة خرائط Google، بما في ذلك الخريطة وعلامات وأدوات الرسم وغير ذلك من خدمات منصة خرائط Google، مثل الأماكن.

إذا كانت لديك خبرة سابقة في واجهة برمجة تطبيقات JavaScript للخرائط، قد تكون على دراية بتحميلها من خلال إدراج علامة script في ملف HTML على النحو التالي:

    <script async defer src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap">

لا تزال هذه طريقة صالحة تمامًا لتحميل واجهة برمجة التطبيقات، ولكن عادةً ما يتم تضمين تبعيات JavaScript الحديثة ديناميكيًا من الرمز. لتحقيق ما يعادل علامة script أعلاه من الرمز، يجب استخدام الوحدة@googlemaps/js-api-loader. يتم تضمين برنامج تحميل واجهة برمجة تطبيقات JavaScript في تبعيات ملف package.json للمشروع، لذا تم تثبيته عند تشغيل npm install في وقت سابق.

لاستخدام برنامج تحميل واجهة برمجة تطبيقات JavaScript، افعل ما يلي:

1. فتح /src/app.js هذا الملف هو المكان الذي ستجري فيه كل أعمالك في هذا الدرس التطبيقي حول الترميز.
2. استيراد الفئة Loader من @googlemaps/js-api-loader.
   
   إضافة ما يلي إلى أعلى app.js:

    import { Loader } from '@googlemaps/js-api-loader';
   

3. أنشئ عنصر apiOptions.
   
   تتطلّب فئة Loader عنصرًا بتنسيق JSON يحدّد خيارات متنوعة لتحميل واجهة برمجة تطبيقات JavaScript لـ "خرائط Google"، بما في ذلك مفتاح واجهة برمجة تطبيقات "منصة خرائط Google" وإصدار إصدار واجهة برمجة التطبيقات الذي تريد تحميله وأي مكتبات إضافية توفّرها واجهة برمجة تطبيقات Maps JS التي تريد تحميلها. لأغراض هذا الدرس التطبيقي حول الترميز، ما عليك سوى تحديد مفتاح واجهة برمجة التطبيقات من خلال إلحاق ما يلي بـ app.js:

    const apiOptions = {
      apiKey: "YOUR API KEY"
    }
   

4. أنشِئ مثيل Loader وامنحه apiOptions.

    const loader = new Loader(apiOptions);
   

5. تحميل واجهة برمجة تطبيقات JavaScript JS.
   
   لتحميل واجهة برمجة التطبيقات، عليك طلب load() من خلال مثيل Loader. تعرض أداة التحميل JS API وعودًا يتم حلها بعد تحميل واجهة برمجة التطبيقات وتجهيزها للاستخدام. أضِف التنويه الموجز التالي لتحميل واجهة برمجة التطبيقات ومعالجة عملية الوعد:

    loader.load().then(() => {
      console.log('Maps JS API loaded');
    });
   

في حال نجاح كل ذلك، ستظهر لك عبارة console.log في وحدة التحكّم في المتصفّح:

خلاصة ما سبق، لقد حمّلت الآن واجهة برمجة تطبيقات JavaScript للخرائط ديناميكيًا من الترميز وحددت وظيفة رد الاتصال التي يتم تنفيذها بعد الانتهاء من تحميل واجهة برمجة تطبيقات JavaScript للخرائط.

يجب أن يظهر ملف app.js على النحو التالي:

    import { Loader } from '@googlemaps/js-api-loader';

    const apiOptions = {
      apiKey: "YOUR API KEY"
    }

    const loader = new Loader(apiOptions);

    loader.then(() => {
      console.log('Maps JS API Loaded');
    });

الآن وبعد أن تم تحميل واجهة برمجة تطبيقات JavaScript للخرائط، سيتم تحميل الخريطة في الخطوة التالية.

5. عرض خريطة

حان وقت عرض خريطتك الأولى.

الجزء الأكثر استخدامًا في واجهة برمجة تطبيقات JavaScript للخرائط هو google.maps.Map، وهي الفئة التي تتيح لنا إنشاء مثيلات الخرائط ومعالجتها. ألقِ نظرة على كيفية عمل ذلك من خلال إنشاء دالة جديدة باسم displayMap().

1. حدِّد إعدادات الخريطة.
   
   تتيح واجهة برمجة تطبيقات JavaScript للخرائط مجموعة متنوعة من الإعدادات المختلفة للخريطة، ولكن يجب استخدام إعدادَين فقط:
   • center: لضبط خط العرض وخط الطول لمركز الخريطة.
   • zoom: ضبط مستوى التكبير/التصغير الأولي للخريطة.
   استخدِم الرمز التالي لتحديد مركز الخريطة في "سيدني"، وأستراليا، وامنحه مستوى التكبير أو التصغير 14، وهو مستوى التكبير أو التصغير المناسب لعرض وسط المدينة.

    function displayMap() {
      const mapOptions = {
        center: { lat: -33.860664, lng: 151.208138 },
        zoom: 14
      };
    }
   

2. استخدِم div حيث يجب إدخال الخريطة في نموذج العناصر في المستند.
   
   قبل أن تتمكّن من عرض الخريطة، عليك إخبار واجهة برمجة تطبيقات JavaScript لـ "خرائط Google" بالمكان الذي تريد عرضها فيه على الصفحة. بعد إلقاء نظرة سريعة على index.html، تلاحظ أن هناك div تشبه هذا الآن:

    <div id="map"></div>
   

   لإبلاغ واجهة برمجة تطبيقات JavaScript عن المكان الذي تريد إدخاله في الخريطة، استخدِم document.getElementById للحصول على مرجع DOM الخاص بها:

    const mapDiv = document.getElementById('map');
   

3. أنشِئ مثيل google.maps.Map.
   
   للطلب من واجهة برمجة تطبيقات JavaScript للخرائط إنشاء خريطة جديدة يمكن عرضها، يمكن إنشاء مثيل google.maps.Map وتمرير mapDiv وmapOptions. ويمكنك أيضًا عرض مثيل Map من هذه الدالة حتى تتمكّن من إنجاز المزيد من المهام لاحقًا:

    const map = new google.maps.Map(mapDiv, mapOptions);
    return map;
   

4. عرض الخريطة!
   
   بعد تحديد كل منطق إنشاء مثيل الخريطة، كل ما عليك فعله هو استدعاء displayMap() من معالج الكائن المضمّن في واجهة برمجة تطبيقات JavaScript بحيث يتم طلبه بعد تحميل واجهة برمجة تطبيقات JavaScript للخرائط:

    loader.then(() => {
      console.log('Maps JS API loaded');
      const map = displayMap();
    });
   

ستظهر لك خريطة رائعة لسيدني في متصفحك:

خلاصة القول، لقد حدّدت في هذه الخطوة خيارات العرض للخريطة، وأنشأت مثيل خريطة جديدًا، وأدخلته في نموذج العناصر في المستند.

من المفترض أن تبدو دالة displayMap() على النحو التالي:

function displayMap() {
  const mapOptions = {
    center: { lat: -33.860664, lng: 151.208138 },
    zoom: 14
  };
  const mapDiv = document.getElementById('map');
  const map = new google.maps.Map(mapDiv, mapOptions);
  return map;
}

6- تصميم الخرائط المستنِد إلى السحابة الإلكترونية (اختياري)

يمكنك تخصيص نمط الخريطة باستخدام نمط الخريطة المستنِدة إلى السحابة الإلكترونية.

إنشاء رقم تعريف للخريطة

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

1. إنشاء رقم تعريف للخريطة.
2. ربط رقم تعريف خريطة بنمط الخريطة.

إضافة معرّف الخريطة إلى تطبيقك

لاستخدام رقم تعريف الخريطة الذي أنشأته، عدِّل الدالة displayMap في ملف app.js وادخل رقم تعريف الخريطة في السمة mapId في الكائن mapOptions.

app.js

function displayMap() {
  const mapOptions = {
    center: { lat: -33.860664, lng: 151.208138 },
    zoom: 14,
    mapId: 'YOUR_MAP_ID'
  };
  const mapDiv = document.getElementById('map');
  return new google.maps.Map(mapDiv, mapOptions);
}

بعد الانتهاء من ذلك، سيظهر لك النمط الذي حددته على الخريطة.

7- إضافة علامات إلى الخريطة

هناك العديد من الأمور التي ينفذها مطوّرو البرامج باستخدام واجهة برمجة تطبيقات JavaScript ل"خرائط Google"، إلا أن وضع العلامات على الخريطة هو الأكثر رواجًا بالتأكيد. تتيح لك العلامات عرض نقاط محددة على الخريطة، وتعدّ عنصرًا شائعًا لواجهة المستخدم للتعامل مع المستخدم. إذا كنت قد استخدمت "خرائط Google" من قبل، ربما تكون على دراية بالعلامة التلقائية، التي تبدو كما يلي:

في هذه الخطوة، ستستخدم google.maps.Marker لوضع العلامات على الخريطة.

1. حدِّد عنصرًا لمواقع العلامات.
   
   للبدء، عليك إنشاء دالة addMarkers() جديدة والتصريح عن كائن locations يتضمن المجموعة التالية من نقاط خطوط الطول/العرض لمواقع الجذب السياحي الشهيرة في سيدني.
   
   يُرجى العِلم أيضًا بضرورة تمرير مثيل Map إلى الدالة. ستستخدم ذلك لاحقًا عند إنشاء مثيلات علاماتك.

    function addMarkers(map) {
      const locations = {
        operaHouse: { lat: -33.8567844, lng: 151.213108 },
        tarongaZoo: { lat: -33.8472767, lng: 151.2188164 },
        manlyBeach: { lat: -33.8209738, lng: 151.2563253 },
        hyderPark: { lat: -33.8690081, lng: 151.2052393 },
        theRocks: { lat: -33.8587568, lng: 151.2058246 },
        circularQuay: { lat: -33.858761, lng: 151.2055688 },
        harbourBridge: { lat: -33.852228, lng: 151.2038374 },
        kingsCross: { lat: -33.8737375, lng: 151.222569 },
        botanicGardens: { lat: -33.864167, lng: 151.216387 },
        museumOfSydney: { lat: -33.8636005, lng: 151.2092542 },
        maritimeMuseum: { lat: -33.869395, lng: 151.198648 },
        kingStreetWharf: { lat: -33.8665445, lng: 151.1989808 },
        aquarium: { lat: -33.869627, lng: 151.202146 },
        darlingHarbour: { lat: -33.87488, lng: 151.1987113 },
        barangaroo: { lat: - 33.8605523, lng: 151.1972205 }
      }
    }
   

2. أنشئ مثيل google.maps.Marker لكل علامة تريد عرضها.
   
   لإنشاء العلامات، استخدِم الرمز أدناه لتعديل العنصر locations باستخدام حلقة for...in، وأنشئ مجموعة من الخيارات لكيفية عرض كل علامة، ثم أنشئ مثيل google.maps.Marker لكل موقع جغرافي.
   
   لاحِظ السمة icon من markerOptions. هل تتذكر دبوس الخريطة التلقائي السابق؟ هل كنت تعلم أيضًا أنه يمكنك تخصيص الدبوس ليكون أي صورة تريدها؟ حسنًا، يمكنك ذلك.
   
   تسمح لك السمة icon بتوفير المسار إلى أي ملف صورة تريد استخدامه كعلامة مخصّصة. إذا بدأت هذا الدرس التطبيقي باستخدام نموذج المشروع الخاص بنا، هذا يعني أنه تمّ تضمين صورة لك في /src/images.
   
   لاحظ أيضًا أنك بحاجة إلى تخزين مثيلات العلامات في مصفوفة وعرضها من الدالة حتى يمكن استخدامها لاحقًا.

    const markers = [];
    for (const location in locations) {
      const markerOptions = {
        map: map,
        position: locations[location],
        icon: './img/custom_pin.png'
      }
      const marker = new google.maps.Marker(markerOptions);
      markers.push(marker);
    }
    return markers;
   

3. عرض العلامات
   
   تنشئ واجهة برمجة تطبيقات JavaScript لـ "خرائط Google" علامة تلقائيًا وتعرضها عند إنشاء مثيل جديد من google.maps.Marker، لذا كل ما عليك فعله هو تحديث معالج وعودة JS API لاستدعاء addMarkers() وتمريره مثيل Map:

    loader.then(() => {
      console.log('Maps JS API loaded');
      const map = displayMap();
      const markers = addMarkers(map);
    });
   

يجب أن ترى الآن العلامات المخصصة على الخريطة:

خلاصة القول، لقد حدّدت في هذه الخطوة مجموعة من مواقع العلامات وأنشأت مثيل google.maps.Marker باستخدام رمز علامة مخصّص لكل موقع جغرافي.

من المفترض أن تبدو دالة addMarkers() على النحو التالي:

    function addMarkers(map) {
      const locations = {
        operaHouse: { lat: -33.8567844, lng: 151.213108 },
        tarongaZoo: { lat: -33.8472767, lng: 151.2188164 },
        manlyBeach: { lat: -33.8209738, lng: 151.2563253 },
        hyderPark: { lat: -33.8690081, lng: 151.2052393 },
        theRocks: { lat: -33.8587568, lng: 151.2058246 },
        circularQuay: { lat: -33.858761, lng: 151.2055688 },
        harbourBridge: { lat: -33.852228, lng: 151.2038374 },
        kingsCross: { lat: -33.8737375, lng: 151.222569 },
        botanicGardens: { lat: -33.864167, lng: 151.216387 },
        museumOfSydney: { lat: -33.8636005, lng: 151.2092542 },
        maritimeMuseum: { lat: -33.869395, lng: 151.198648 },
        kingStreetWharf: { lat: -33.8665445, lng: 151.1989808 },
        aquarium: { lat: -33.869627, lng: 151.202146 },
        darlingHarbour: { lat: -33.87488, lng: 151.1987113 },
        barangaroo: { lat: - 33.8605523, lng: 151.1972205 }
      }
      const markers = [];
      for (const location in locations) {
        const markerOptions = {
          map: map,
          position: locations[location],
          icon: './img/custom_pin.png'
        }
        const marker = new google.maps.Marker(markerOptions);
        markers.push(marker);
      }
      return markers;
    }

في الخطوة التالية، ستتعرّف على كيفية تحسين تجربة المستخدم للعلامات باستخدام تجميع العلامات.

8- تفعيل تجميع العلامات

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

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

تقسِّم خوارزمية تجميع العلامات المنطقة المرئية من الخريطة إلى شبكة، ثم تجمّع الرموز في الخلية نفسها. لحسن الحظ، لا داعي للقلق بشأن أي شيء بسبب ذلك، أنشأ فريق"منصة خرائط Google"مكتبة برامج مفتوحة المصدر مفيدة تسمى MarkerClustererPlus وتنفّذ كل ما تريده تلقائيًا. يمكنك عرض المصدر لـ MarkerClustererPluson GitHub.

1. استيراد MarkerCluster.
   
   بالنسبة إلى مشروع النموذج لهذا الدرس التطبيقي، تكون مكتبة أدوات MarkerClustererPlus مضمّنة مسبقًا في التبعيات المحدّدة في ملف package.json، وبالتالي سبق لك تثبيتها عند تشغيل npm install في بداية هذا الدرس التطبيقي حول الترميز.
   
   لاستيراد المكتبة، أضِف ما يلي إلى أعلى ملف app.js:

    import MarkerClusterer from '@google/markerclustererplus';
   

2. إنشاء مثيل جديد من MarkerClusterer.
   
   لإنشاء مجموعات علامات، عليك تنفيذ أمرَين: توفير الرموز التي تريد استخدامها لمجموعات العلامات وإنشاء مثيل جديد من MarkerClusterer.
   
   أولاً، اذكر كائنًا يحدد مسار الرموز التي تريد استخدامها. يتوفّر حاليًا في مجموعة النماذج مجموعة من الصور المحفوظة في ./img/m. لاحظ أنه يتم ترقيم أسماء ملفات الصور بالتسلسل باستخدام البادئة نفسها: m1.png وm2.png وm3.png وما إلى ذلك.
   
   عند ضبط الخاصية imagePath في خيارات مجمِّع العلامات، ما عليك سوى توفير المسار وبادئة الملف وستستخدِم أداة تجميع العلامات تلقائيًا جميع الملفات التي تبدأ بهذه البادئة وأضِف رقمًا إلى النهاية.
   
   ثانيًا، أنشئ مثيلاً جديدًا من MarkerClusterer ومرِّر مثيل Map حيث تريد عرض مجموعات العلامات ومصفوفة من Marker نسخة افتراضية تريد تجميعها.

    function clusterMarkers(map, markers) {
      const clustererOptions = { imagePath: './img/m' }
      const markerCluster = new MarkerClusterer(map, markers, clustererOptions);
    }
   

3. عرض مجموعات علامات
   
   سيتم استدعاء clusterMarkers() من معالج الكائن المضمّن في واجهة برمجة تطبيقات JavaScript. تتم إضافة مجموعات العلامات تلقائيًا إلى الخريطة عند إنشاء مثيل MarkerClusterer في استدعاء الدالة.

    loader.then(() => {
      console.log('Maps JS API loaded');
      const map = displayMap();
      const markers = addMarkers(map);
      clusterMarkers(map, markers);
    });
   

من المفترض أن يظهر لك الآن بعض مجموعات علامات على خريطتك.

يُرجى العِلم أنّه في حال التكبير أو التصغير، سيعيد برنامج مقاس ClustererPlus تغيير عدد المجموعات وتغيير حجمها تلقائيًا. يمكنك أيضًا النقر على أي رمز مجموعة علامات لتكبيره والتعرّف على جميع العلامات المتضمّنة في هذه المجموعة.

للملخّص، في هذه الخطوة، أجريت استيرادًا لمكتبة الأدوات المساعدة المفتوحة المصدر MarkerClustererPlus واستخدمتها لإنشاء مثيل من MarkerClusterer جمّع تلقائيًا العلامات التي أنشأتها في الخطوة السابقة.

من المفترض أن تبدو دالة clusterMarkers() على النحو التالي:

    function clusterMarkers(map, markers) {
      const clustererOptions = { imagePath: './img/m' }
      const markerCluster = new MarkerClusterer(map, markers, clustererOptions);
    }

بعد ذلك، ستتعرّف على كيفية التعامل مع تفاعل المستخدمين.

9- إضافة تفاعل المستخدم

لديك الآن خريطة رائعة تعرض بعض الوجهات السياحية الأكثر شهرة في سيدني. في هذه الخطوة، ستضيف بعض المعالجة الإضافية لتفاعلات المستخدم باستخدام نظام الأحداث في واجهة برمجة تطبيقات JavaScript للخرائط لتحسين تجربة المستخدم على خريطتك بشكلٍ أكبر.

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

في هذه الخطوة، ستضيف مستمعًا للنقر إلى علاماتك، ثم تجعل تحريك الخريطة آليًا لوضع العلامة التي نقر عليها المستخدم في منتصف الخريطة.

1. اضبط أداة معالجة النقر على علاماتك.
   
   تعمل جميع العناصر في واجهة برمجة تطبيقات JavaScript للخرائط التي تدعم نظام الأحداث على تنفيذ مجموعة عادية من الدوال لمعالجة تفاعل المستخدم، مثل addListener وremoveListener وغيرها.
   
   لإضافة أداة معالجة حدث النقر إلى كل علامة، كرِّر المصفوفة markers واستدعِ addListener إلى مثيل العلامة لإرفاق أداة معالجة للحدث click:

    function addPanToMarker(map, markers) {
      markers.map(marker => {
        marker.addListener('click', event => {
   
        });
      });
    }
   

2. العرض الشامل لأحد العلامات عندما يتم النقر عليه.
   
   يتم تشغيل حدث click عندما ينقر المستخدِم على محدِّد موقع، ويتم عرض حدث كعنصر JSON يحتوي على معلومات عن عنصر واجهة المستخدم الذي تم النقر عليه. لتحسين تجربة المستخدم للخريطة، يمكنك التعامل مع حدث click واستخدام الكائن LatLng للحصول على خط العرض وخط الطول للعلامة التي تم النقر عليها.
   
   وبعد الحصول على ذلك، ما عليك سوى تمرير ذلك إلى دالة panTo() المُدمجة في Map' لكي يتم تحريك الخريطة بسلاسة إلى أحدث في علامة تم النقر عليها عن طريق إضافة ما يلي في دالة رد الاتصال في معالج الحدث:

    const location = { lat: event.latLng.lat(), lng: event.latLng.lng() };
    map.panTo(location);
   

3. خصّص أدوات معالجة النقرات.
   
   يجب استدعاء addPanToMarker() من معالج الوعد الخاص بواجهة برمجة تطبيقات JavaScript، وتمرير الخريطة والعلامات لتمييز تنفيذ الرمز وتحديد مستمعي النقر.

    loader.then(() => {
      console.log('Maps JS API loaded');
      const map = displayMap();
      const markers = addMarkers(map);
      clusterMarkers(map, markers);
      addPanToMarker(map, markers);
    });
   

انتقل الآن إلى المتصفح وانقر على "العلامات". من المفترض أن يظهر لك الخريطة تلقائيًا عرضًا أحدث عندما يتم النقر على محدّد الموقع.

وباختصار، في هذه الخطوة، استخدمت نظام الأحداث في واجهة برمجة تطبيقات JavaScript لـ "خرائط Google" لتعيين مستمع النقر إلى جميع العلامات على الخريطة، وتم استرداد خط العرض وخط الطول للعلامة من حدث النقر الذي تم تنشيطه، واستخدمته لتعيد الخريطة كلما تم النقر على العلامة.

من المفترض أن تبدو دالة addPanToMarker() على النحو التالي:

    function addPanToMarker(map, markers) {
      markers = markers.map(marker => {
        marker.addListener('click', event => {
          const location = { lat: event.latLng.lat(), lng: event.latLng.lng() };
          map.panTo(location);
        });
      });
      return markers;
    }

يتبقّى خطوة واحدة فقط. بعد ذلك، ستتمكن من تحسين تجربة المستخدم للخريطة بشكل أكبر باستخدام ميزات الرسم في واجهة برمجة تطبيقات JavaScript للخرائط.

10- الرسم على الخريطة

حتى الآن، أنشأت خريطة لسيدني تعرض علامات للوجهات السياحية الشهيرة وتتعامل مع تفاعل المستخدم. بالنسبة إلى الخطوة الأخيرة من هذا الدرس التطبيقي، ستستخدِم ميزات الرسم في واجهة برمجة تطبيقات JavaScript لـ "خرائط Google" لإضافة ميزة أخرى مفيدة إلى تجربتك في الخرائط.

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

تتضمن واجهة برمجة تطبيقات JavaScript للخرائط مجموعة من الدوال لرسم الأشكال على الخريطة، مثل المربّعات والمضلعات والخطوط والدوائر. بعد ذلك، ستعرض دائرة حول نصف قطر حول 800 متر (ما يقرب من نصف ميل) حول العلامة عند النقر عليه.

1. ارسم دائرة باستخدام google.maps.Circle.
   
   دوال الرسم في واجهة برمجة تطبيقات JavaScript للخرائط تمنحك مجموعة كبيرة من الخيارات حول كيفية ظهور عنصر مرسوم على الخريطة. لعرض نصف قطر دائري، أعلن عن مجموعة من الخيارات لدائرة، مثل اللون ووزن الخط، حيث يجب توسيط الدائرة ونطاقها الجغرافي، ثم أنشئ مثيلًا جديدًا من google.maps.Circle لإنشاء دائرة جديدة:

    function drawCircle(map, location) {
      const circleOptions = {
        strokeColor: '#FF0000',
        strokeOpacity: 0.8,
        strokeWeight: 1,
        map: map,
        center: location,
        radius: 800
      }
      const circle = new google.maps.Circle(circleOptions);
      return circle;
    }
   

2. ارسم الدائرة عند النقر على العلامة.
   
   لرسم الدائرة عندما ينقر المستخدم على علامة، كل ما عليك فعله هو استدعاء دالة drawCircle() التي كتبتها أعلاه من معاودة الاستماع التي تستمع إلى النقرة في addPanToMarker()، وتمريرها وموقعها.
   
   لاحظ كيف تتم أيضًا إضافة عبارة شرطية تؤدي إلى استدعاء circle.setMap(null). يؤدي ذلك إلى إزالة الدائرة المعروضة سابقًا من الخريطة إذا نقر المستخدم على علامة أخرى، حتى لا تنتهي بخريطة مغطاة في دوائر أثناء استكشاف المستخدم للخريطة.
   
   من المفترض أن تبدو الدالة addPanToMarker() على النحو التالي:

    function addPanToMarker(map, markers) {
      let circle;
      markers.map(marker => {
        marker.addListener('click', event => {
          const location = { lat: event.latLng.lat(), lng: event.latLng.lng() };
          map.panTo(location);
          if (circle) {
            circle.setMap(null);
          }
          circle = drawCircle(map, location);
        });
      });
    }
   

اطّلعت على كل النصائح. انتقِل إلى المتصفّح، وانقر على إحدى العلامات. سيظهر لك نطاق جغرافي دائري معروض:

11- تهانينا

لقد نجحت في إنشاء أول تطبيق ويب باستخدام Google Maps Platform، بما في ذلك تحميل واجهة برمجة تطبيقات JavaScript للخرائط، وتحميل خريطة، والعمل باستخدام علامات، والتحكّم على الخريطة ورسمها، وإضافة تفاعل المستخدمين.

وللاطّلاع على الرمز المكتمل، اطّلِع على المشروع المكتمل في دليل /solutions.

ما الخطوات التالية؟

في هذا الدرس التطبيقي حول الترميز، تناولت أساسيات ما يمكنك فعله باستخدام واجهة برمجة تطبيقات JavaScript لـ "خرائط Google". بعد ذلك، حاول إضافة بعض هذه الميزات إلى الخريطة:

• غيِّر نوع الخريطة لعرض الخرائط القمر الصناعي والمختلط والتضاريس.
• تفعيل الترجمة لتحميل الخريطة بلغات مختلفة.
• تخصيص تفاعلات المستخدم الأخرى مثل التكبير/التصغير وعناصر التحكم في الخريطة
• أضِف نوافذ المعلومات لعرض المعلومات عند النقر على العلامات.
• اطّلِع على المكتبات الإضافية المتاحة لواجهة برمجة تطبيقات JavaScript للخرائط والتي توفّر وظائف إضافية، مثل "الأماكن" و"الرسم" و"التمثيل البصري".

لمواصلة التعرّف على المزيد من الطرق التي يمكنك من خلالها العمل مع "منصة خرائط Google" على الويب، اطّلِع على الروابط التالية:

• مستندات واجهة برمجة تطبيقات JavaScript للخرائط
• قناة YouTube على "منصة خرائط Google"
• الدروس التطبيقية حول ترميز "منصة خرائط Google"
• مشاريع مفتوحة المصدر في "منصة خرائط Google" على GitHub