کاوش مکان با PlaceSearchElement

هدف اصلی

با نحوه ادغام کردن PlaceSearchElement با Google Maps آشنا شوید تا به کاربران کمک کنید مکان‌ها را بااستفاده از جستجوی اطراف یا جستجوی نوشتار پیدا کنند و توانایی‌شان را برای کاوش نقاط جالب تقویت کنید. از «عنصر فشرده جزئیات مکان» برای ارائه جزئیات بیشتر درباره مکان‌های نشان‌داده‌شده در برنامه‌تان استفاده کنید.

PlaceSearchElement چیست؟

‫PlaceSearchElement بخشی از «کیت میانای کاربر جاها» در میانای برنامه‌سازی کاربردی جاوا اسکریپت Maps است. این عنصر HTML نتایج جستجوی مکان را مستقیماً در قالب فهرست در برنامه شما ارائه می‌دهد. این عنصر فرایند نمایش مکان‌های یافت‌شده بااستفاده از «جستجوی اطراف» یا «جستجوی نوشتار» را ساده می‌کند و تجربه کاربری یکپارچه‌ای برای کاوش مکان ارائه می‌دهد. وقتی کاربر مکانی را از فهرست انتخاب می‌کند، می‌توانید جزئیات آن را روی نقشه نمایش دهید، معمولاً بااستفاده از «پنجره اطلاعات» و «عنصر جزئیات مکان».

تجسم کاوش مکان

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

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

ادغام PlaceSearchElement می‌تواند برنامه‌های مختلف را در صنایع مختلف بهبود بخشد:

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

گردش کار راه‌حل: پیاده‌سازی «کاوش مکان»

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

پیش‌نیازها

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

• PlaceSearchElement - برای نمایش مکان‌ها بااستفاده از «جستجوی اطراف» یا «جستجوی نوشتار» استفاده می‌شود
• عنصر جزئیات جا - برای نمایش جزئیات یک مکان خاص استفاده می‌شود
• Maps JavaScript API - برای نشان دادن نقشه در صفحه‌تان و وارد کردن «کیت میانای کاربر جاها» استفاده می‌شود

میانای برنامه‌سازی کاربردی جاوا اسکریپت Maps و کیت میانای کاربر «جاها» را در پروژه‌تان فعال کنید.

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

افزودن نقشه به صفحه

اولین قدم افزودن نقشه به صفحه‌تان است. این نقشه برای نمایش نتایج PlaceSearchElement به‌صورت سنجاق‌های قابل‌انتخاب استفاده خواهد شد.

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

1. استفاده از gmp-map جزء وب HTML.
2. بااستفاده از JavaScript.

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

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

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

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

راه‌اندازی PlaceSearchElement

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

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

در کد اچ‌تی‌ام‌ال خود، عنصر <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>

برای انجام جستجوی اولیه و نمایش نتایج، از جاوا اسکریپت برای دریافت مرجع عنصر درخواست تودرتو و تنظیم ویژگی‌های آن استفاده خواهیم کرد. یک Circle را برای استفاده به‌عنوان 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'];

نمونه‌ای از ظاهر احتمالی برنامه در این مرحله در زیر آمده است:

اجازه دادن به کاربر برای جستجو کردن

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

• <gmp-place-nearby-search-request> - نتایج جستجو را از جستجوی اطراف Places بااستفاده از انواع مکان ارائه دهید.
• <gmp-place-text-search-request> - نتایج جستجو را از جستجوی نوشتار Places بااستفاده از ورودی نوشتار آزاد مثل «سوشی در سانفرانسیسکو» ارائه می‌دهد.

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

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

جستجوی اطراف

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

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

نمایش سنجاق‌ها و جزئیات مکان

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

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

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

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

let markers = {};

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

• هرگونه نشانگر مکان موجود را از نقشه بردارید.
• نتایج PlaceSearchElement را به‌صورت حلقه‌ای مرور کنید و برای هرکدام نشانگری اضافه کنید.
• مرزهای نقشه را تنظیم کنید تا همه نشانگرهای جدید قابل‌مشاهده باشند.

برای گوش دادن به زمانی که نتایج جستجو دردسترس است، شنونده رویداد 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);
    }
}

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

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

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 برای ارائه کل محتوای عنصر ارسال می‌شود. برای انتخاب اینکه کدام محتوا پرداز شود، به سند عنصر فشرده جزئیات مکان مراجعه کنید.

متغیری سراسری در جاوا اسکریپت ایجاد کنید تا مرجعی برای «عنصر فشرده جزئیات جا» نگه دارد و این را در کد مقداردهی اولیه خود پر کنید، برای مثال:

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();
    }
});

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

درخواست به‌صورت زیر خواهد بود:

نتیجه‌گیری

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

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

همیاران

هنریک والو | مهندس DevX