اجزای وب در Maps JavaScript API (پیش نمایش)

Web Components یک استاندارد محبوب W3C است که HTML، CSS و JS را در عناصر HTML سفارشی و قابل استفاده مجدد محصور می کند. این اجزای قابل استفاده مجدد می توانند از عملکردهای اتمی مانند نمایش رتبه بندی ستاره برای یک مکان تا منطق تجاری پیچیده تر متغیر باشند. این راهنما اجزای وب موجود در Maps JavaScript API را شرح می دهد.

برای اطلاعات بیشتر در مورد خود استاندارد، به Web Components مراجعه کنید.

حضار

این مستندات به گونه ای طراحی شده است که به شما امکان می دهد به سرعت کاوش و توسعه برنامه ها را با مؤلفه های وب شروع کنید. شما باید با مفاهیم برنامه نویسی 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;

جاوا اسکریپت

// 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>

Sample را امتحان کنید

در این مثال چند نکته قابل توجه است:

  1. Maps JavaScript API به صورت ناهمزمان فراخوانی می شود. تابع callback برای اطلاع از زمان بارگیری API استفاده می شود.
  2. ارائه نقشه با عنصر سفارشی <gmp-map> تعریف می شود.
  3. ویژگی های نقشه با تعیین ویژگی ها در عنصر سفارشی <gmp-map> تعریف می شوند.
  4. استایل را می توان به صورت درون خطی برای عناصر سفارشی اعمال کرد یا در یک فایل CSS جداگانه اعلام کرد.

بیس مپ را سبک کنید

شناسه نقشه یک شناسه مرتبط با سبک یا ویژگی خاص نقشه است. برای بهره‌گیری از ویژگی‌های اختیاری پیکربندی ابر، نقشه‌های مبتنی بر ابر به سبک DEMO_MAP_ID را با شناسه نقشه خود جایگزین کنید. برای آشنایی با نحوه ایجاد شناسه نقشه و پیکربندی یک سبک سفارشی، از استایل نقشه‌های مبتنی بر Cloud دیدن کنید.

نشانگرها را به نقشه اضافه کنید

همانطور که می‌توان تگ‌های 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;

جاوا اسکریپت

// 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>

Sample را امتحان کنید

در اینجا ما دو عنصر <gmp-advanced-marker> را در داخل عنصر سفارشی <gmp-map> اضافه کرده‌ایم. متن برای title یک متن شناور اضافی و برچسب دسترسی برای عنصر مشخص شده فراهم می کند.

رویدادهای جاوا اسکریپت

یکی از مزایای اصلی Web Component ها سهولت استفاده است. با چند خط کد می توان نقشه ای را با دانش محدود جاوا اسکریپت یا برنامه نویسی پیشرفته نمایش داد. پس از پیاده سازی، کد از الگوهای آشنای دیگر عناصر 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;

جاوا اسکریپت

// 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>

Sample را امتحان کنید

در این مثال، initMap تابع تماس مورد نیاز را پس از بارگیری کامل Maps JavaScript API نشان می دهد. کد شنوندگان هر نشانگر را ایجاد می کند و با کلیک روی هر نشانگر یک پنجره اطلاعاتی را ارائه می دهد.

بعدش چی