مكونات الويب في Maps API API (معاينة)

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

لمزيد من المعلومات عن المعيار نفسه، اطلع على مكونات الويب.

الجمهور

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

عرض خريطة

تتمثل أسهل طريقة لبدء التعرف على مكونات الويب في رؤية مثال. يعرض المثال التالي خريطة لمنطقة سان خوسيه.

خريطة منطقة سان خوسيه

HTML

<html>
  <head>
    <title>Simple Map</title>
    <link rel="stylesheet" type="text/css" href="style.css" />

    <script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap&libraries=maps,marker&v=beta">
    </script>

    <script>
      function initMap() {
        console.log('Maps JavaScript API loaded.');
      }
    </script>

  </head>
  <body>
    <gmp-map center="37.4220656,-122.0840897" zoom="10" map-id="DEMO_MAP_ID"></gmp-map>
  </body>
</html>

CSS

    gmp-map {
      height: 500px;
    }

في هذا المثال، هناك بعض الأشياء التي يجب ملاحظتها:

  1. يُطلق على Maps JavaScript API اسم غير متزامن. تُستخدم وظيفة معاودة الاتصال لمعرفة وقت تحميل واجهة برمجة التطبيقات.
  2. يتم تحديد عرض الخريطة باستخدام العنصر <gmp-map> المخصّص.
  3. يتم تحديد خصائص الخريطة من خلال تحديد السمات في العنصر <gmp-map> المخصص.
  4. يمكن تطبيق النمط مضمّنًا على العناصر المخصصة أو تعريفه في ملف CSS منفصل.

اختيار تصميم الخريطة الأساسية

معرف الخريطة هو معرف مرتبط بنمط خريطة أو ميزة معينة. للاستفادة من ميزات ضبط السحابة الإلكترونية الاختيارية، يمكنك استبدال تصميم الخرائط المستنِدة إلى السحابة الإلكترونية DEMO_MAP_ID بمعرّف الخريطة الخاص بك. للاطّلاع على كيفية إنشاء معرّف خريطة وضبط نمط مخصّص، عليك الانتقال إلى أنماط الخرائط المستنِدة إلى السحابة الإلكترونية.

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

مثلما يمكن للمرء دمج علامات HTML المضمّنة لإنشاء تسلسلات هرمية للمحتوى المعقد، يمكن للمرء أيضًا دمج <gmp-advanced-marker> داخل عنصر لعرض علامة خريطة واحدة أو أكثر.

خريطة بعلامات

HTML

<html>
  <head>
    <title>Simple Map with Markers</title>
    <link rel="stylesheet" type="text/css" href="style.css" />

    <script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY_HERE&callback=initMap&libraries=maps,marker&v=beta">
    </script>

    <script>
      function initMap() {
        console.log('Maps JavaScript API loaded.');
      }
    </script>

  </head>
  <body>
    <gmp-map center="43.4142989,-124.2301242" zoom="4" map-id="DEMO_MAP_ID">
      <gmp-advanced-marker position="37.4220656,-122.0840897" title="Mountain View, CA"></gmp-advanced-marker>
      <gmp-advanced-marker position="47.648994,-122.3503845" title="Seattle, WA"></gmp-advanced-marker>
    </gmp-map>
  </body>
</html>

CSS

    gmp-map {
      height: 500px;
    }

أضفنا هنا عنصري <gmp-advanced-marker> داخل العنصر المخصص <gmp-map>. يوفر النص الخاص بـ title نص تمرير إضافيًا وتصنيف تسهيل الاستخدام للعنصر المحدد.

أحداث JavaScript

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

حدث النقر على العلامة

HTML

<html>
<head>
  <title>Google Maps - Marker Click Example</title>
  <link rel="stylesheet" href="style.css" type="text/css">

  <script async
  src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY_HERE&callback=initMap&libraries=maps,marker&v=beta">
  </script>

  <script>
    function initMap() {
      console.log('Maps JavaScript API loaded.');

      const advancedMarkers = document.querySelectorAll("#marker-click-event-example gmp-advanced-marker");
      for (const advancedMarker of advancedMarkers) {
        customElements.whenDefined(advancedMarker.localName).then(async () => {
          advancedMarker.addEventListener('gmp-click', async () => {
            const {InfoWindow} = await google.maps.importLibrary("maps");
            const infoWindow = new InfoWindow({
              content: advancedMarker.title
            });
            infoWindow.open({
              anchor: advancedMarker
            });
          });
        });
      }
    }
  </script>
</head>
<body>

<gmp-map id="marker-click-event-example" center="43.4142989,-124.2301242" zoom="4" map-id="DEMO_MAP_ID">
  <gmp-advanced-marker position="37.4220656,-122.0840897" title="Mountain View, CA"></gmp-advanced-marker>
  <gmp-advanced-marker position="47.648994,-122.3503845" title="Seattle, WA"></gmp-advanced-marker>
</gmp-map>

</body>
</html>

CSS

    gmp-map {
      height: 500px;
    }

في هذا المثال، تمثل initMap دالة معاودة الاتصال المطلوبة بعد أن يتم تحميل Maps JavaScript API بالكامل. ينشئ الكود المستمعين لكل علامة ويقدم نافذة معلومات عند النقر على كل علامة.

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