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

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

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

الجمهور

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

عرض خريطة

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

TypeScript

// This example adds a map using web components.
function initMap(): void {
    console.log('Maps JavaScript API loaded.');
}

declare global {
    interface Window {
        initMap: () => void;
    }
}
window.initMap = initMap;

JavaScript

// This example adds a map using web components.
function initMap() {
  console.log("Maps JavaScript API loaded.");
}

window.initMap = initMap;

CSS

/* 
 * Always set the map height explicitly to define the size of the div element
 * that contains the map. 
 */
#map {
  height: 100%;
}

/* 
 * Optional: Makes the sample page fill the window. 
 */
html,
body {
  height: 100%;
  margin: 0;
  padding: 0;
}

gmp-map {
  height: 400px;
}

HTML

<html>
  <head>
    <title>Add a Map Web Component</title>
    <script src="https://polyfill.io/v3/polyfill.min.js?features=default"></script>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <gmp-map
      center="37.4220656,-122.0840897"
      zoom="10"
      map-id="DEMO_MAP_ID"
    ></gmp-map>

    <!-- 
      The `defer` attribute causes the callback to execute after the full HTML
      document has been parsed. For non-blocking uses, avoiding race conditions,
      and consistent behavior across browsers, consider loading using Promises.
      See https://developers.google.com/maps/documentation/javascript/load-maps-js-api
      for more information.
      -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initMap&v=beta"
      defer
    ></script>
  </body>
</html>

تجربة النموذج

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

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

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

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

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

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

TypeScript

// This example adds a map with markers, using web components.
function initMap(): void {
    console.log('Maps JavaScript API loaded.');
}

declare global {
    interface Window {
        initMap: () => void;
    }
}
window.initMap = initMap;

JavaScript

// This example adds a map with markers, using web components.
function initMap() {
  console.log("Maps JavaScript API loaded.");
}

window.initMap = initMap;

CSS

/* 
 * Always set the map height explicitly to define the size of the div element
 * that contains the map. 
 */
#map {
  height: 100%;
}

/* 
 * Optional: Makes the sample page fill the window. 
 */
html,
body {
  height: 100%;
  margin: 0;
  padding: 0;
}

gmp-map {
  height: 400px;
}

HTML

<html>
  <head>
    <title>Add a Map with Markers using Web Components</title>
    <script src="https://polyfill.io/v3/polyfill.min.js?features=default"></script>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></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>

    <!-- 
      The `defer` attribute causes the callback to execute after the full HTML
      document has been parsed. For non-blocking uses, avoiding race conditions,
      and consistent behavior across browsers, consider loading using Promises.
      See https://developers.google.com/maps/documentation/javascript/load-maps-js-api
      for more information.
      -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initMap&libraries=marker&v=beta"
      defer
    ></script>
  </body>
</html>

تجربة النموذج

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

أحداث JavaScript

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

في ملف HTML، اضبط السمة gmp-clickable على العنصر gmp-advanced-marker لتصبح العلامة قابلة للنقر. استخدِم "advancedMarker.addEventListener" للتعامل مع أحداث النقر

TypeScript

// This example adds a map using web components.
function initMap(): void {
  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 = new google.maps.InfoWindow({
          //@ts-ignore
          content: advancedMarker.title,
        });
        infoWindow.open({
          //@ts-ignore
          anchor: advancedMarker
        });
      });
    });
  }
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;

JavaScript

// This example adds a map using web components.
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 = new google.maps.InfoWindow({
          //@ts-ignore
          content: advancedMarker.title,
        });

        infoWindow.open({
          //@ts-ignore
          anchor: advancedMarker,
        });
      });
    });
  }
}

window.initMap = initMap;

CSS

/* 
 * Always set the map height explicitly to define the size of the div element
 * that contains the map. 
 */
#map {
  height: 100%;
}

/* 
 * Optional: Makes the sample page fill the window. 
 */
html,
body {
  height: 100%;
  margin: 0;
  padding: 0;
}

gmp-map {
  height: 400px;
}

HTML

<html>
  <head>
    <title>Add a Map Web Component with Events</title>
    <script src="https://polyfill.io/v3/polyfill.min.js?features=default"></script>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></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-clickable
      ></gmp-advanced-marker>
      <gmp-advanced-marker
        position="47.648994,-122.3503845"
        title="Seattle, WA"
        gmp-clickable
      ></gmp-advanced-marker>
    </gmp-map>

    <!-- 
      The `defer` attribute causes the callback to execute after the full HTML
      document has been parsed. For non-blocking uses, avoiding race conditions,
      and consistent behavior across browsers, consider loading using Promises.
      See https://developers.google.com/maps/documentation/javascript/load-maps-js-api
      for more information.
      -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initMap&libraries=marker&v=beta"
      defer
    ></script>
  </body>
</html>

تجربة النموذج

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

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