این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

یک نقشه به وب سایت خود اضافه کنید (جاوا اسکریپت)

1. قبل از شروع

در این لبه کد، همه چیزهایی را که برای شروع استفاده از پلتفرم نقشه های گوگل برای وب نیاز دارید، یاد می گیرید. شما تمام اصول اولیه را یاد می گیرید، از راه اندازی گرفته تا بارگیری Maps JavaScript API، نمایش اولین نقشه خود، کار با نشانگرها و خوشه بندی نشانگرها، طراحی روی نقشه، و مدیریت تعامل با کاربر.

چیزی که خواهی ساخت

در این کد لبه، شما یک برنامه وب ساده می سازید که کارهای زیر را انجام می دهد:

Maps JavaScript API را بارگیری می کند
نقشه ای را در مرکز سیدنی استرالیا نمایش می دهد
نشانگرهای سفارشی را برای جاذبه های محبوب در سیدنی نمایش می دهد
خوشه بندی نشانگر را پیاده سازی می کند
تعامل کاربر را فعال می‌کند که وقتی روی یک نشانگر کلیک می‌شود، دایره‌ای را روی نقشه تازه‌سازی می‌کند و می‌کشد

چیزی که یاد خواهید گرفت

شروع کار با پلتفرم نقشه های گوگل
بارگیری API جاوا اسکریپت Maps به صورت پویا از کد جاوا اسکریپت
در حال بارگیری نقشه
استفاده از نشانگرها، نشانگرهای سفارشی و خوشه بندی نشانگرها
کار با سیستم رویداد Maps JavaScript API برای ارائه تعامل با کاربر
کنترل نقشه به صورت پویا
طراحی روی نقشه

2. پیش نیازها

برای تکمیل این Codelab باید با موارد زیر آشنا شوید. اگر قبلاً با کار با Google Maps Platform آشنا هستید، به Codelab بروید!

محصولات پلتفرم Google Maps مورد نیاز

در این Codelab، از محصولات پلتفرم Google Maps زیر استفاده خواهید کرد:

Maps JavaScript API
کتابخانه خوشه‌بندی نشانگر منبع باز MarkerClustererPlus

سایر الزامات این Codelab

برای تکمیل این کد لبه، به حساب‌ها، خدمات و ابزارهای زیر نیاز دارید:

یک حساب Google Cloud Platform با فعال کردن صورت‌حساب
یک کلید API پلتفرم Google Maps با فعال کردن API جاوا اسکریپت Maps
دانش اولیه جاوا اسکریپت، HTML و CSS
Node.js روی رایانه شما نصب شده است
یک ویرایشگر متن یا IDE به انتخاب شما

با پلتفرم نقشه های گوگل شروع کنید

اگر قبلاً از Google Maps Platform استفاده نکرده‌اید، راهنمای Get Started with Google Maps Platform را دنبال کنید یا لیست پخش Started with Google Maps Platform را برای تکمیل مراحل زیر تماشا کنید:

یک حساب صورتحساب ایجاد کنید.
یک پروژه ایجاد کنید.
APIها و SDKهای پلتفرم Google Maps را فعال کنید (در قسمت قبل فهرست شده است).
یک کلید API ایجاد کنید.

3. راه اندازی کنید

پلتفرم نقشه های گوگل را راه اندازی کنید

اگر قبلاً یک حساب Google Cloud Platform و پروژه‌ای با صورت‌حساب فعال ندارید، لطفاً راهنمای شروع به کار با Google Maps Platform را برای ایجاد یک حساب صورت‌حساب و یک پروژه ببینید.

در Cloud Console ، روی منوی کشویی پروژه کلیک کنید و پروژه ای را که می خواهید برای این کد لبه استفاده کنید انتخاب کنید.

APIها و SDKهای پلتفرم Google Maps مورد نیاز برای این لبه کد را در Google Cloud Marketplace فعال کنید. برای انجام این کار، مراحل این ویدیو یا این مستند را دنبال کنید.
یک کلید API در صفحه Credentials در Cloud Console ایجاد کنید. می توانید مراحل این ویدئو یا این مستند را دنبال کنید. همه درخواست‌ها به پلتفرم Google Maps به یک کلید API نیاز دارند.

راه اندازی Node.js

اگر قبلاً آن را ندارید، به https://nodejs.org/ بروید تا زمان اجرا Node.js را دانلود و بر روی رایانه خود نصب کنید.

Node.js با مدیریت بسته npm ارائه می شود که باید وابستگی هایی را برای این کد لبه نصب کنید.

راه اندازی قالب شروع پروژه

قبل از شروع این کد لبه، برای دانلود قالب پروژه شروع کننده و همچنین کد راه حل کامل، موارد زیر را انجام دهید:

مخزن GitHub را برای این کد لبه در https://github.com/googlecodelabs/maps-platform-101-js بارگیری یا جدا کنید.

پروژه شروع در دایرکتوری /starter قرار دارد و شامل ساختار فایل اصلی است که برای تکمیل کد لبه نیاز دارید. هر چیزی که برای کار با آن نیاز دارید در فهرست /starter/src قرار دارد. 2. پس از دانلود پروژه استارتر، npm install در پوشه /starter اجرا کنید. این همه وابستگی های مورد نیاز فهرست شده در package.json را نصب می کند. 3. هنگامی که وابستگی های شما نصب شد، npm start در دایرکتوری اجرا کنید.

پروژه شروع برای شما تنظیم شده است تا از webpack-dev-server استفاده کنید، که کدی را که شما به صورت محلی می نویسید را کامپایل و اجرا می کند. webpack-dev-server همچنین هر زمان که کد را تغییر دهید به طور خودکار برنامه شما را در مرورگر بارگیری می کند.

اگر می‌خواهید کد راه‌حل کامل را در حال اجرا ببینید، می‌توانید مراحل راه‌اندازی بالا را در پوشه /solution کامل کنید.

4. Maps JavaScript API را بارگیری کنید

قبل از شروع، لطفاً مطمئن شوید که مراحل راه‌اندازی را دنبال کرده‌اید. همه چیز تمام شد؟ بسیار خوب، وقت آن است که اولین برنامه وب خود را با استفاده از پلتفرم Google Maps بسازید!

اساس استفاده از پلتفرم نقشه های گوگل برای وب، Maps JavaScript API است. این API یک رابط جاوا اسکریپت برای استفاده از تمام ویژگی‌های پلتفرم نقشه‌های گوگل، از جمله نقشه، نشانگرها، ابزارهای ترسیم و سایر خدمات پلتفرم نقشه‌های گوگل، مانند مکان‌ها، ارائه می‌کند.

اگر تجربه قبلی با Maps JavaScript API دارید، ممکن است با بارگیری آن با قرار دادن یک تگ script در یک فایل HTML مانند این آشنا باشید:

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

این هنوز یک روش کاملاً معتبر برای بارگیری API است، اما در جاوا اسکریپت مدرن وابستگی ها معمولاً به صورت پویا از کد گنجانده می شوند. برای انجام معادل تگ script بالا از کد، از ماژول @googlemaps/js-api-loader استفاده خواهید کرد. JS API Loader قبلاً در وابستگی های فایل package.json پروژه گنجانده شده است، بنابراین زمانی که npm install زودتر اجرا کردید، نصب شد.

برای استفاده از JS API Loader، موارد زیر را انجام دهید:

/src/app.js را باز کنید. این فایل جایی است که شما تمام کارهای خود را برای این کد لبه انجام خواهید داد.
کلاس Loader از @googlemaps/js-api-loader وارد کنید.

موارد زیر را به بالای app.js اضافه کنید:
```
 import { Loader } from '@googlemaps/js-api-loader';
```
یک شی apiOptions ایجاد کنید.

کلاس Loader به یک شی JSON نیاز دارد که گزینه‌های مختلفی را برای بارگیری Maps JavaScript API، از جمله کلید API پلتفرم Google Maps، نسخه API که می‌خواهید بارگیری کنید و هر کتابخانه اضافی ارائه شده توسط Maps JS API که می‌خواهید بارگیری کنید، مشخص می‌کند. برای اهداف این کد لبه، فقط باید کلید API را با ضمیمه کردن موارد زیر به app.js مشخص کنید:
```
 const apiOptions = {
   apiKey: "YOUR API KEY"
 }
```
یک نمونه از Loader ایجاد کنید و apiOptions خود را ارسال کنید.
```
 const loader = new Loader(apiOptions);
```
Maps JS API را بارگیری کنید.

برای بارگذاری API، load() در نمونه Loader فراخوانی کنید. JS API Loader وعده ای را برمی گرداند که پس از بارگیری API و آماده شدن برای استفاده برطرف می شود. برای بارگیری API و مدیریت وعده، خرد زیر را اضافه کنید:
```
 loader.load().then(() => {
   console.log('Maps JS API loaded');
 });
```

اگر همه چیز موفقیت آمیز بود، باید عبارت console.log را در کنسول مرورگر ببینید. با استفاده از Chrome، این پنجره اضافی در View -> Developer -> Javascript Console قابل دسترسی است.

برای جمع بندی، اکنون به صورت پویا Maps JavaScript API را از روی کد بارگیری کرده اید و تابع callback را تعریف کرده اید که پس از بارگیری Maps JavaScript API اجرا می شود.

فایل app.js شما باید چیزی شبیه به این باشد:

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

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

    const loader = new Loader(apiOptions);

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

اکنون که Maps JavaScript API بارگذاری شده است، در مرحله بعد نقشه را بارگیری خواهید کرد.

5. نمایش یک نقشه

زمان نمایش اولین نقشه شماست!

متداول ترین قسمت استفاده شده از Maps JavaScript API google.maps.Map است که به ما امکان می دهد نمونه های نقشه را ایجاد و دستکاری کنیم. با ایجاد یک تابع جدید به نام displayMap() به نحوه انجام این کار نگاهی بیندازید.

تنظیمات نقشه خود را مشخص کنید.

Maps JavaScript API از تنظیمات مختلف برای نقشه پشتیبانی می کند، اما تنها دو مورد نیاز است:
- center : طول و عرض جغرافیایی را برای مرکز نقشه تنظیم می کند.
- zoom : سطح بزرگنمایی اولیه نقشه را تنظیم می کند.
از کد زیر برای وسط نقشه در سیدنی استرالیا استفاده کنید و به آن سطح زوم 14 بدهید که فقط سطح زوم مناسبی برای نشان دادن مرکز شهر است.
```
 function displayMap() {
   const mapOptions = {
     center: { lat: -33.860664, lng: 151.208138 },
     zoom: 14
   };
 }
```
div را دریافت کنید که در آن نقشه باید به DOM تزریق شود.

قبل از اینکه بتوانید نقشه را نمایش دهید، باید به Maps JavaScript API بگویید کجا می خواهید در صفحه نمایش داده شود. اگر نگاهی گذرا به index.html بیندازید، می بینید که قبلاً یک div به شکل زیر وجود دارد:
```
 <div id="map"></div>
```
برای اینکه به Maps JavaScript API بگویید این جایی است که می‌خواهید نقشه تزریق شود، از document.getElementById برای دریافت مرجع DOM آن استفاده کنید:
```
 const mapDiv = document.getElementById('map');
```
یک نمونه از google.maps.Map ایجاد کنید.

برای درخواست از Maps JavaScript API برای ایجاد یک نقشه جدید که می‌تواند نمایش داده شود، یک نمونه از google.maps.Map ایجاد کنید و mapDiv و mapOptions وارد کنید. شما همچنین نمونه Map را از این تابع برمی گردانید تا بتوانید بعداً کارهای بیشتری با آن انجام دهید:
```
 const map = new google.maps.Map(mapDiv, mapOptions);
 return map;
```
نمایش نقشه!

هنگامی که تمام منطق ایجاد نمونه نقشه خود را تعریف کردید، تنها چیزی که باقی می‌ماند این است که displayMap() از کنترلر وعده JS API فراخوانی کنید تا پس از بارگیری Maps JavaScript API فراخوانی شود:
```
 loader.then(() => {
   console.log('Maps JS API loaded');
   const map = displayMap();
 });
```

اکنون باید نقشه زیبای سیدنی را در مرورگر خود مشاهده کنید:

به طور خلاصه، در این مرحله شما گزینه های نمایش نقشه را تعریف کردید، یک نمونه نقشه جدید ایجاد کردید و آن را به DOM تزریق کردید.

تابع 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. طراحی نقشه مبتنی بر ابر (اختیاری)

می توانید سبک نقشه خود را با استفاده از استایل نقشه مبتنی بر ابر سفارشی کنید.

یک شناسه نقشه ایجاد کنید

اگر هنوز شناسه نقشه با سبک نقشه مرتبط با آن ایجاد نکرده‌اید، برای تکمیل مراحل زیر، راهنمای Map IDs را ببینید:

یک شناسه نقشه ایجاد کنید.
شناسه نقشه را به سبک نقشه مرتبط کنید.

افزودن شناسه نقشه به برنامه شما

برای استفاده از شناسه نقشه ای که ایجاد کرده اید، تابع 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. نشانگرها را به نقشه اضافه کنید

کارهای زیادی وجود دارد که توسعه دهندگان با Maps JavaScript API انجام می دهند، اما قرار دادن نشانگرها روی نقشه قطعاً محبوب ترین آنهاست. نشانگرها به شما امکان می‌دهند نقاط خاصی را روی نقشه نشان دهید و یک عنصر رابط کاربری مشترک برای مدیریت تعامل کاربر هستند. اگر قبلاً از Google Maps استفاده کرده‌اید، احتمالاً با نشانگر پیش‌فرض آشنا هستید که به شکل زیر است:

در این مرحله از google.maps.Marker برای قرار دادن نشانگرها روی نقشه استفاده خواهید کرد.

یک شی برای مکان های نشانگر خود تعریف کنید.

برای شروع، یک تابع 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 }
   }
 }

برای هر نشانگری که می خواهید نمایش داده شود، یک نمونه از google.maps.Marker ایجاد کنید.

برای ایجاد نشانگرهای خود، از کد زیر استفاده کنید تا با استفاده از یک حلقه for...in در میان شی locations تکرار کنید، مجموعه‌ای از گزینه‌ها را برای نحوه نمایش هر نشانگر ایجاد کنید، و سپس یک نمونه از 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;
```
نشانگرها را نمایش دهید

Maps JavaScript API هر زمان که نمونه جدیدی از 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. خوشه بندی نشانگر را فعال کنید

هنگام استفاده از بسیاری از نشانگرها یا نشانگرها که در مجاورت یکدیگر قرار دارند، ممکن است با مشکلی روبرو شوید که نشانگرها روی هم قرار می گیرند یا خیلی شلوغ به نظر می رسند که باعث تجربه کاربری بدی می شود. به عنوان مثال، پس از ایجاد نشانگرها در مرحله آخر، ممکن است متوجه این موضوع شده باشید:

این جایی است که خوشه‌بندی نشانگر وارد می‌شود. خوشه‌بندی نشانگر یکی دیگر از ویژگی‌های رایج است که نشانگرهای نزدیک را در یک نماد گروه‌بندی می‌کند که بسته به سطح بزرگ‌نمایی تغییر می‌کند، مانند این:

الگوریتم برای خوشه بندی نشانگر، منطقه قابل مشاهده نقشه را به یک شبکه تقسیم می کند، سپس نمادهایی را که در همان سلول هستند، خوشه بندی می کند. خوشبختانه، لازم نیست نگران هیچ‌کدام از این موارد باشید، زیرا تیم پلتفرم نقشه‌های گوگل یک کتابخانه ابزار مفید و منبع باز به نام MarkerClustererPlus ایجاد کرده است که همه چیز را به صورت خودکار برای شما انجام می‌دهد. می توانید منبع MarkerClustererPluson GitHub را مشاهده کنید.

MarkerCluster را وارد کنید.

برای پروژه الگوی این کد لبه، کتابخانه ابزار MarkerClustererPlus قبلاً در وابستگی‌های اعلام شده در فایل package.json گنجانده شده است، بنابراین شما قبلاً آن را هنگام اجرای npm install در ابتدای این کد لبه نصب کرده‌اید.

برای وارد کردن کتابخانه، موارد زیر را به بالای فایل app.js خود اضافه کنید:
```
 import MarkerClusterer from '@google/markerclustererplus';
```
یک نمونه جدید از 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);
 }
```
نمایش خوشه های نشانگر

فراخوانی clusterMarkers() از کنترل کننده وعده JS API. هنگامی که نمونه MarkerClusterer در فراخوانی تابع ایجاد می شود، خوشه های نشانگر به طور خودکار به نقشه اضافه می شوند.
```
 loader.then(() => {
   console.log('Maps JS API loaded');
   const map = displayMap();
   const markers = addMarkers(map);
   clusterMarkers(map, markers);
 });
```

اکنون باید چند خوشه نشانگر را روی نقشه خود ببینید.

توجه داشته باشید که اگر بزرگ‌نمایی یا کوچک‌نمایی کنید، MarkerClustererPlus به‌طور خودکار خوشه‌ها را برای شما شماره‌گذاری کرده و اندازه آن‌ها را تغییر می‌دهد. همچنین می توانید روی هر نماد خوشه نشانگر کلیک کنید تا بزرگنمایی کنید و همه نشانگرهای موجود در آن خوشه را ببینید.

برای جمع بندی، در این مرحله شما کتابخانه ابزار منبع باز MarkerClustererPlus را وارد کردید و از آن برای ایجاد نمونه ای از MarkerClusterer استفاده کردید که به طور خودکار نشانگرهایی را که در مرحله قبل ایجاد کردید، خوشه بندی کرد.

تابع clusterMarkers() شما باید چیزی شبیه به این باشد:

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

در مرحله بعد، نحوه مدیریت تعامل کاربر را یاد خواهید گرفت.

9. تعامل کاربر را اضافه کنید

اکنون یک نقشه عالی دارید که برخی از محبوب ترین مقاصد گردشگری سیدنی را نشان می دهد. در این مرحله، با استفاده از سیستم رویداد Maps JavaScript API برای بهبود بیشتر تجربه کاربری نقشه خود، برخی از مدیریت های اضافی تعاملات کاربر را اضافه خواهید کرد.

Maps JavaScript API یک سیستم رویداد جامع را ارائه می‌کند که از کنترل‌کننده‌های رویداد جاوا اسکریپت استفاده می‌کند تا به شما امکان می‌دهد تا تعاملات مختلف کاربر را در کد مدیریت کنید. برای مثال، می‌توانید شنونده‌های رویداد ایجاد کنید تا اجرای کد را برای فعل و انفعالاتی مانند کلیک کاربر روی نقشه و نشانگرها، جابجایی نمای نقشه، بزرگ‌نمایی و کوچک‌نمایی و غیره ایجاد کنید.

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

یک شنونده کلیک روی نشانگرهای خود تنظیم کنید.

همه اشیاء موجود در Maps JavaScript API که از سیستم رویداد پشتیبانی می‌کنند، مجموعه‌ای استاندارد از توابع را برای مدیریت تعامل کاربر اجرا می‌کنند، مانند addListener ، removeListener ، و غیره.

برای افزودن شنونده رویداد کلیکی به هر نشانگر، آرایه markers را تکرار کنید و addListener در نمونه نشانگر فراخوانی کنید تا شنونده ای برای رویداد click متصل شود:
```
 function addPanToMarker(map, markers) {
   markers.map(marker => {
     marker.addListener('click', event => {

     });
   });
 }
```
هنگامی که روی یک نشانگر کلیک می شود، آن را به سمت نشانگر حرکت دهید.

رویداد click هر زمان که کاربر روی یک نشانگر کلیک یا ضربه می‌زند فعال می‌شود و رویدادی را به‌عنوان یک شی JSON با اطلاعاتی درباره عنصر UI که روی آن کلیک شده است، برمی‌گرداند. برای بهبود تجربه کاربری نقشه، می‌توانید رویداد click را مدیریت کنید و از شی LatLng آن برای دریافت طول و عرض جغرافیایی نشانگری که روی آن کلیک شده است استفاده کنید.

هنگامی که آن را به دست آوردید، به سادگی آن را به تابع داخلی panTo() نمونه Map ارسال کنید تا با افزودن موارد زیر در تابع callback کنترل کننده رویداد، نقشه به آرامی بر روی نشانگر کلیک شده حرکت کند:
```
 const location = { lat: event.latLng.lat(), lng: event.latLng.lng() };
 map.panTo(location);
```
شنوندگان کلیک را اختصاص دهید.

addPanToMarker() از کنترلر وعده JS API فراخوانی کنید و نقشه و نشانگرهای خود را برای اجرای کد ارسال کنید و شنوندگان کلیک خود را اختصاص دهید.
```
 loader.then(() => {
   console.log('Maps JS API loaded');
   const map = displayMap();
   const markers = addMarkers(map);
   clusterMarkers(map, markers);
   addPanToMarker(map, markers);
 });
```

حالا به مرورگر بروید و روی نشانگرهای خود کلیک کنید. هنگامی که روی یک نشانگر کلیک می‌شود، باید نقشه را به‌طور خودکار به سمت جدیدتر حرکت دهید.

برای جمع‌بندی، در این مرحله، از سیستم رویداد Maps JavaScript API برای اختصاص دادن یک شنونده کلیک به همه نشانگرهای روی نقشه استفاده کردید، طول و عرض جغرافیایی نشانگر را از رویداد کلیک اجرا شده بازیابی کردید، و از آن برای تغییر مجدد نقشه هر زمان که روی یک نشانگر کلیک شد استفاده کردید.

تابع 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;
    }

فقط یک قدم دیگر باقی مانده است! در مرحله بعد، با استفاده از ویژگی‌های ترسیم Maps JavaScript API، تجربه کاربری نقشه را بیشتر بهبود می‌بخشید.

10. روی نقشه بکشید

تاکنون نقشه ای از سیدنی ایجاد کرده اید که نشانگرهایی را برای مقاصد گردشگری محبوب نشان می دهد و تعامل کاربر را مدیریت می کند. برای آخرین مرحله از این نرم افزار کد، از ویژگی های ترسیم Maps JavaScript API برای افزودن یک ویژگی مفید اضافی به تجربه نقشه خود استفاده خواهید کرد.

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

Maps JavaScript API شامل مجموعه ای از توابع برای ترسیم اشکال بر روی نقشه است، مانند مربع، چند ضلعی، خطوط و دایره. در مرحله بعد، دایره‌ای را رندر می‌دهید تا شعاع 800 متری (تقریباً نیم مایل) در اطراف یک نشانگر را با کلیک روی آن نشان دهید.

با google.maps.Circle یک دایره بکشید.

توابع ترسیم در Maps JavaScript API گزینه های بسیار متنوعی را برای نحوه نمایش یک شی ترسیم شده روی نقشه در اختیار شما قرار می دهد. برای ارائه یک شعاع دایره‌ای، مجموعه‌ای از گزینه‌ها را برای یک دایره، مانند رنگ، وزن ضربه، جایی که دایره و شعاع آن باید در مرکز قرار گیرد، اعلام کنید، سپس یک نمونه جدید از 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;
 }
```
وقتی روی یک نشانگر کلیک می شود دایره را بکشید.

برای رسم دایره هنگامی که کاربر روی یک نشانگر کلیک می کند، تنها کاری که باید انجام دهید این است که تابع drawCircle() را که در بالا نوشتید از callback listener در 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، از جمله بارگیری Maps JavaScript API، بارگیری نقشه، کار با نشانگرها، کنترل و ترسیم روی نقشه، و افزودن تعامل با کاربر، ساختید.

برای مشاهده کد تکمیل شده، پروژه تمام شده را در پوشه /solutions بررسی کنید.

بعدش چی؟

در این کد لبه، شما اصول اولیه کارهایی را که می توانید با Maps JavaScript API انجام دهید، پوشش دادید. در مرحله بعد، برخی از این ویژگی ها را به نقشه اضافه کنید:

نوع نقشه را برای نمایش نقشه های ماهواره ای، ترکیبی و زمین تغییر دهید.
محلی سازی را برای بارگیری نقشه به زبان های مختلف فعال کنید.
سایر تعاملات کاربر مانند زوم و کنترل های نقشه را سفارشی کنید.
پنجره های اطلاعاتی را برای نمایش اطلاعات در هنگام کلیک روی نشانگرها اضافه کنید.
کتابخانه‌های اضافی موجود برای Maps JavaScript API را بررسی کنید که عملکردهای اضافی مانند مکان‌ها، طراحی و تجسم را فعال می‌کنند.

برای ادامه یادگیری روش‌های بیشتر برای کار با Google Maps Platform در وب، این پیوندها را بررسی کنید: