مکان‌ها را با عنصر جستجوی مکان و API جاوا اسکریپت Maps کشف کنید

هدف

بیاموزید که چگونه عنصر جستجوی مکان را با Google Maps ادغام کنید تا به کاربران کمک کند مکان‌ها را با استفاده از جستجوی نزدیک یا جستجوی نوشتاری پیدا کنند و توانایی آن‌ها را برای کشف نقاط مورد علاقه افزایش دهد. از عنصر فشرده جزئیات مکان برای ارائه جزئیات بیشتر در مورد مکان های ظاهر شده در برنامه خود استفاده کنید.

عنصر جستجوی مکان چیست؟

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

کشف مکان را تجسم کنید

تصویر زیر نمونه ای از عنصر جستجوی مکان را در عمل نشان می دهد. در سمت چپ، لیستی از رستوران ها نمایش داده می شود (عنصر جستجوی مکان). هنگامی که رستورانی انتخاب می شود، جزئیات آن در یک پنجره اطلاعات روی نقشه ظاهر می شود و نقشه بر روی مکان آن متمرکز می شود.

تصویر

از موارد برای کشف مکان استفاده کنید

ادغام عنصر جستجوی مکان می تواند کاربردهای مختلف را در صنایع مختلف افزایش دهد:

  • سفر و جهانگردی: به گردشگران اجازه دهید تا جاذبه ها، هتل ها یا انواع خاصی از غذاها را در یک منطقه جستجو کنند.
  • املاک و مستغلات: خریداران یا اجاره‌کنندگان بالقوه را فعال کنید تا مدارس، سوپرمارکت‌ها یا گزینه‌های حمل‌ونقل عمومی اطراف را بیابند.
  • تدارکات و خدمات: به رانندگان در یافتن ایستگاه های شارژ EV، پمپ بنزین ها یا مراکز خدمات خاص کمک کنید.

گردش کار راه حل: پیاده سازی مکان کشف

این بخش شما را در مراحل ادغام عنصر جستجوی مکان برای کشف مکان‌ها روی نقشه راهنمایی می‌کند، از جمله قطعات کد برای تعامل با کیت UI Places. ما مقداردهی اولیه نقشه و اجرای هر دو قابلیت جستجوی نزدیک و جستجوی متن را پوشش خواهیم داد. در نهایت، از عنصر Place Details برای نشان دادن جزئیات بیشتر در مورد یک مکان خاص، با کلیک روی پین آن روی نقشه استفاده می‌کنیم.

پیش نیازها

آشنایی با مدارک زیر توصیه می شود:

  • عنصر جستجوی مکان - برای نمایش مکان ها با استفاده از جستجوی نزدیک یا جستجوی متن استفاده می شود
  • عنصر جزئیات مکان - برای نمایش جزئیات یک مکان جداگانه استفاده می شود
  • Maps JavaScript API - برای نمایش نقشه در صفحه شما و وارد کردن Places UI Kit استفاده می شود

Maps JavaScript API و Places UI Kit را در پروژه خود فعال کنید.

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

یک نقشه به صفحه اضافه کنید

اولین قدم این است که یک نقشه به صفحه خود اضافه کنید. این نقشه برای نمایش نتایج عنصر جستجوی مکان به عنوان پین های قابل انتخاب استفاده خواهد شد.

دو راه برای اضافه کردن نقشه به یک صفحه وجود دارد:

  1. استفاده از کامپوننت وب gmp-map HTML .
  2. با استفاده از جاوا اسکریپت

قطعه کد موجود در این صفحه با استفاده از نقشه جاوا اسکریپت ایجاد شده است.

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

اگر در حال تجسم مکان های نزدیک به یک مکان ثابت مانند یک هتل هستید، یک نشانگر برای نشان دادن این مکان روی نقشه قرار دهید . به عنوان مثال:

تصویر

این نقشه در مرکز سانفرانسیسکو قرار دارد، با یک سنجاق آبی برای نشان دادن مکانی که ما در این نزدیکی جستجو می کنیم. رنگ پین با استفاده از PinElement سفارشی شده است. کنترل Map Type از رابط کاربری پنهان شده است.

عنصر جستجوی مکان را تنظیم کنید

اکنون می‌توانیم HTML و CSS را برای نمایش عنصر جستجوی مکان تنظیم کنیم. برای این مثال، ما می‌خواهیم عنصر را در سمت چپ نقشه شناور کنیم، اما توصیه می‌شود طرح‌بندی‌های مختلفی را متناسب با برنامه خود امتحان کنید.

عنصر جستجوی مکان از یک رویکرد اعلامی استفاده می کند. به جای پیکربندی کامل آن در جاوا اسکریپت، نوع جستجو را مستقیماً در HTML خود با قرار دادن یک عنصر درخواست، مانند <gmp-place-nearby-search-request> در داخل مؤلفه اصلی <gmp-place-search> تعریف می کنید.

در کد HTML خود، عنصر <gmp-place-search> را مقداردهی اولیه کنید. برای فعال کردن رویدادهای کلیک روی نتایج از ویژگی selectable استفاده کنید. در داخل آن، یک <gmp-place-nearby-search-request> اضافه کنید تا مشخص کنید که این عنصر برای جستجوی اطراف استفاده خواهد شد.

<gmp-place-search selectable>
  <gmp-place-nearby-search-request>
  </gmp-place-nearby-search-request>
</gmp-place-search>

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

قطعه کد برای این به شرح زیر است:

// Get references to the Place Search and its nested request element
const placeSearchElement = document.querySelector("gmp-place-search");
const placeSearchRequestElement = document.querySelector("gmp-place-nearby-search-request");

// Define the location restriction for the search
const circleRestriction = new Circle({
    center: marker.position,
    radius: 500
});

// Set the properties on the request element to perform an initial search for restaurants.
placeSearchRequestElement.locationRestriction = circleRestriction;
placeSearchRequestElement.includedPrimaryTypes = ['restaurant'];

نمونه ای از نحوه نگاه کردن برنامه در این مرحله به شرح زیر است:

تصویر

عنصر جستجوی مکان دو گزینه جستجو را امکان پذیر می کند:

اینها عناصر تو در تو در داخل <gmp-place-search> هستند. سپس با تنظیم ویژگی‌ها در آن عنصر درخواست تودرتو با استفاده از جاوا اسکریپت، جستجوها را آغاز می‌کنید.

این بخش پیاده سازی هر دو روش را شرح می دهد.

تصویر

برای اینکه کاربران بتوانند جستجوی نزدیک را انجام دهند، ابتدا به یک عنصر UI نیاز دارید تا بتوانند نوع مکان را انتخاب کنند. روش انتخابی را انتخاب کنید که برای برنامه شما بهترین کار را دارد، به عنوان مثال، یک لیست کشویی پر از مجموعه ای از انواع مکان ها.

توصیه می شود زیرمجموعه ای از انواع را انتخاب کنید که مربوط به مورد استفاده شما هستند. برای مثال، اگر در حال توسعه برنامه‌ای هستید تا به گردشگران نشان دهید چه چیزی در نزدیکی هتل است، می‌توانید موارد زیر را انتخاب کنید: bakery ، coffee_shop ، museum ، restaurant و tourist_attraction .

HTML شما باید حاوی عنصر <gmp-place-search> با <gmp-place-nearby-search-request> باشد که در داخل آن قرار دارد.

<gmp-place-search selectable>
  <gmp-place-nearby-search-request>
  </gmp-place-nearby-search-request>
</gmp-place-search>

سپس، یک شنونده جاوا اسکریپت برای رویداد change در انتخابگر نوع مکان خود ایجاد کنید. این شنونده تابعی را فراخوانی می‌کند که ویژگی‌های عنصر <gmp-place-nearby-search-request> را به‌روزرسانی می‌کند، که به طور خودکار یک جستجوی جدید را آغاز می‌کند و لیست را به‌روزرسانی می‌کند.

// Get a reference to the nested request element
const placeSearchRequestElement = document.querySelector('gmp-place-nearby-search-request');

// Function to update the place search based on the selected type
function updatePlaceList() {
    const selectedType = placeTypeSelect.value;
    if (!selectedType) {
        // If no type is selected, don't perform a search.
        // You could optionally hide the list or clear previous results here.
        placeSearchElement.style.display = 'none';
        return;
    }
    placeSearchElement.style.display = 'block';

    // Set properties on the request element to trigger a new search
    placeSearchRequestElement.locationRestriction = searchCircle;
    placeSearchRequestElement.maxResultCount = 8;
    placeSearchRequestElement.includedPrimaryTypes = [selectedType];
}

همان searchCircle از مرحله راه‌اندازی برای locationRestriction استفاده می‌شود. ویژگی includedPrimaryTypes روی مقدار انتخابی کاربر تنظیم می شود. یک maxResultCount اختیاری نیز برای محدود کردن تعداد نتایج تنظیم شده است.

جستجوی متن

تصویر

برای فعال کردن جستجوی متن، پیکربندی HTML شما باید تغییر کند. به جای درخواست جستجوی نزدیک، یک عنصر <gmp-place-text-search-request> را قرار می دهید.

<gmp-place-search selectable>
  <gmp-place-text-search-request>
  </gmp-place-text-search-request>
</gmp-place-search>

یک ورودی متن و یک دکمه جستجو به رابط کاربری خود اضافه کنید. یک شنونده جاوا اسکریپت برای رویداد click دکمه ایجاد کنید. کنترل کننده رویداد ورودی کاربر را می گیرد و ویژگی های عنصر <gmp-place-text-search-request> را برای انجام جستجو به روز می کند.

// Get a reference to the text search request element
const placeTextSearchRequestElement = document.querySelector('gmp-place-text-search-request');
const textSearchInput = document.getElementById('textSearchInput');
const textSearchButton = document.getElementById('textSearchButton');

textSearchButton.addEventListener('click', performTextSearch);

function performTextSearch() {
    const query = textSearchInput.value.trim();
    if (!query) {
        console.log("Search query is empty.");
        return;
    }
    // Set properties on the request element to trigger a new search
    placeTextSearchRequestElement.textQuery = query;
    placeTextSearchRequestElement.locationBias = map.getBounds();
    placeTextSearchRequestElement.maxResultCount = 8;
}

در اینجا، ویژگی textQuery را با ورودی کاربر تنظیم می کنیم. ما همچنین یک locationBias با استفاده از کران‌های نقشه فعلی ارائه می‌کنیم، که به API می‌گوید نتایج را در آن منطقه ترجیح دهد بدون اینکه آنها را محدود کند. یک maxResultCount اختیاری تعداد نتایج برگشتی را محدود می کند.

نمایش پین ها و جزئیات مکان

اکنون برنامه می تواند جستجوی مکان انجام دهد و عنصر را پر کند. در مرحله بعدی عملکرد آن را با موارد زیر افزایش خواهیم داد:

  • نمایش پین ها روی نقشه برای هر مکان پر شده در عنصر جستجوی مکان.
  • به کاربر اجازه می‌دهد روی یک پین یا مکانی در عنصر جستجوی مکان کلیک کند تا جزئیات بیشتری درباره آن مکان خاص نشان دهد.

اصل این مرحله چه برنامه از جستجوی نزدیک یا یک جستجوی متنی استفاده کند، یکسان است.

ابتدا یک متغیر سراسری به کد جاوا اسکریپت خود اضافه کنید تا نشانگرهای مکان را ذخیره کنید. این به شما امکان می دهد وقتی جستجو تغییر می کند آنها را حذف کنید و رویدادهای کلیک را مدیریت کنید.

let markers = {};

یک تابع برای اضافه کردن نشانگرها به نقشه ایجاد کنید. هر زمان که نتایج جستجوی جدید بارگیری شود، این تابع فراخوانی می شود. این خواهد شد:

  • هر نشانگر مکان موجود را از نقشه بردارید.
  • نتایج را از عنصر جستجوی مکان مرور کنید و برای هر یک نشانگر اضافه کنید.
  • مرزهای نقشه را طوری تنظیم کنید که همه نشانگرهای جدید قابل مشاهده باشند.

برای گوش دادن به زمانی که نتایج جستجو در دسترس هستند، یک شنونده رویداد gmp-load به عنصر <gmp-place-search> اضافه کنید. این رویداد پس از تکمیل جستجو و ارائه نتایج فعال می شود.

ما شنونده را در تابع جستجوی خود اضافه می کنیم (به عنوان مثال، updatePlaceList )، و از گزینه { once: true } استفاده می کنیم تا مطمئن شویم که فقط برای نتایج جستجوی فعلی فعال می شود.

// In your search function, after setting the request properties:
placeSearchElement.addEventListener('gmp-load', addMarkers, { once: true });

تابع addMarkers به ​​شکل زیر است:

async function addMarkers() {
    const { LatLngBounds } = await google.maps.importLibrary("core");
    const bounds = new LatLngBounds();

    if (placeSearchElement.places.length > 0) {
        // Remove existing markers
        for (const m in markers) {
            markers[m].map = null;
        }
        markers = {};

        // Loop through each place from the search results
        // and add a marker for each one.
        for (const place of placeSearchElement.places) {
            const marker = new google.maps.marker.AdvancedMarkerElement({
                map: map,
                position: place.location,
            });

            markers[place.id] = marker;
            bounds.extend(place.location);
            marker.collisionBehavior = google.maps.CollisionBehavior.REQUIRED_AND_HIDES_OPTIONAL;

            // Add a click listener for each marker.
            marker.addListener('gmp-click', (event) => {
                // The main logic for showing details will go here.
            });
        }
        // Position the map to display all markers.
        map.setCenter(bounds.getCenter());
        map.fitBounds(bounds);
    }
}

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

تصویر

اکنون که نشانگرها را روی نقشه داریم، آخرین مرحله مدیریت رویدادهای کلیک نشانگر و عنصر برای نمایش یک پنجره اطلاعاتی با جزئیات مکان است که توسط عنصر جزئیات مکان ارائه شده است. برای این مثال، ما از Place Details Compact Element استفاده خواهیم کرد.

برای مثال، HTML عنصر فشرده جزئیات مکان را به کد خود اضافه کنید:

<gmp-place-details-compact orientation="vertical" style="display: none;">
    <gmp-place-all-content></gmp-place-all-content>
    <gmp-place-attribution light-scheme-color="gray" dark-scheme-color="white"></gmp-place-attribution>
</gmp-place-details-compact>

style برای display: none ; تا زمانی که مورد نیاز نباشد قابل مشاهده نخواهد بود. gmp-place-all-content برای ارائه تمام محتوای عنصر ارسال می شود. برای انتخاب محتوا برای ارائه، به مستندات Place Details Compact Element مراجعه کنید.

یک متغیر سراسری در جاوا اسکریپت ایجاد کنید تا ارجاع به عنصر Compact Details را نگه دارد و آن را در کد اولیه خود پر کنید، به عنوان مثال: 

let placeDetailsElement;
...
placeDetailsElement = document.querySelector('gmp-place-details-compact');

در تابع addMarkers ، یک شنونده رویداد gmp-click به هر نشانگر اضافه کنید، و عنصر فشرده جزئیات مکان را پیکربندی کنید تا با ارسال شناسه مکان نشانگر فعلی، جزئیات مکان را نشان دهد.

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

در نهایت، نقشه در نمای مکان انتخاب شده قرار می گیرد و آن را قابل مشاهده می کند. 

async function addMarkers() {
          ...
            marker.addListener('gmp-click', (event) => {
                //Set up Place Details Compact Widget
                placeDetailsElement.style.display = "block";
                // Remove any existing place request element
                const existingPlaceRequest = placeDetailsElement.querySelector('gmp-place-details-place-request');
                if (existingPlaceRequest) {
                    existingPlaceRequest.remove();
                }
                // Create and configure the new place request element
                const placeRequestElement = new google.maps.places.PlaceDetailsPlaceRequestElement({ place: place.id });
                // Prepend the new place request element to the main widget
                placeDetailsElement.prepend(placeRequestElement);
                if (infoWindow.isOpen) {
                    infoWindow.close();
                }
                infoWindow.setOptions({
                    content: placeDetailsElement
                });
                infoWindow.open({
                    anchor: marker,
                    map: map
                });
                // Position the map to show the selected place
                placeDetailsElement.addEventListener('gmp-load', () => {
                    map.fitBounds(place.viewport, { top: 500, left: 400 });
                });
            });
          ...
        });
    }
}

برای اینکه کاربر بتواند روی مکانی در عنصر فهرست مکان کلیک کند تا عنصر فشرده جزئیات مکان را نشان دهد، موارد زیر را پس از تماس برای configureFromSearchNearbyRequest به کد جاوا اسکریپت اضافه کنید. 

placeSearchElement.addEventListener("gmp-select", ({ place }) => {
    if (markers[place.id]) {
        markers[place.id].click();
    }
});

پس از تکمیل این مرحله، برنامه می‌تواند از جستجوی نزدیک یا جستجوی متن برای پر کردن عنصر فهرست مکان استفاده کند. نتایج این کار، پین‌هایی را روی نقشه نشان می‌دهد، و با کلیک کردن روی یک پین یا مکانی در عنصر فهرست مکان، یک پنجره اطلاعات با جزئیات مکان ارائه شده توسط عنصر فشرده جزئیات مکان نشان داده می‌شود.

برنامه به شکل زیر خواهد بود:

تصویر

نتیجه گیری

عنصر جستجوی مکان همراه با عنصر فشرده جزئیات مکان، راهی ساده برای افزودن ویژگی‌های غنی مکان یابی به برنامه‌های پلتفرم Google Maps شما ارائه می‌کند.

همین امروز Places UI Kit را امتحان کنید تا به کاربران خود قدرت دهید تا مکان‌ها را با استفاده از جستجوهای نزدیک و متنی پیدا و کاوش کنند و جزئیات مکان غنی را نمایش دهند و تعامل آنها با موارد استفاده اکتشاف مکان شما افزایش یابد.

مشارکت کنندگان

Henrik Valve | مهندس DevX