Чтобы переводить контент на ваш предпочитаемый язык, Google использует технологии на основе искусственного интеллекта. Переводы от ИИ могут содержать ошибки.

Поиск мест с помощью PlaceSearchElement

Цель

Узнайте, как интегрировать PlaceSearchElement с Google Картами, чтобы пользователи могли находить места с помощью поиска поблизости или текстового поиска. Используйте элемент Place Details Compact, чтобы предоставить больше информации о местах, показанных в вашем приложении.

Что такое `PlaceSearchElement`

PlaceSearchElement – это часть Places UI Kit в Maps JavaScript API. Это элемент HTML, который показывает результаты поиска мест в виде списка прямо в приложении. Этот элемент упрощает показ мест, найденных с помощью поиска поблизости или текстового поиска, и делает его более удобным для пользователей. Когда пользователь выбирает место из списка, вы можете показать подробную информацию о нем на карте, например в информационном окне или элементе с информацией о месте.

Визуализация поиска мест

На изображении ниже показан пример работы PlaceSearchElement. Слева показан список ресторанов (PlaceSearchElement). Если выбрать ресторан, на карте появится информационное окно с подробными сведениями о нем, а карта будет центрирована по его местоположению.

Примеры использования Place Discovery

Интеграция PlaceSearchElement может улучшить различные приложения в разных отраслях:

Путешествия и туризм. Позвольте туристам искать достопримечательности, гостиницы или определенные типы кухни в регионе.
Недвижимость. Потенциальные покупатели или арендаторы могут найти поблизости школы, супермаркеты или остановки общественного транспорта.
Логистика и услуги. Помощь водителям в поиске станций зарядки ЭМ, заправок или сервисных центров.

Рабочий процесс решения: реализация поиска мест

В этом разделе рассказывается, как интегрировать PlaceSearchElement для поиска мест на карте, и приводятся фрагменты кода для взаимодействия с Places UI Kit. Узнайте, как инициализировать карту и реализовать поиск поблизости и текстовый поиск. Наконец, используйте элемент Place Details, чтобы показывать больше информации о месте, когда пользователь нажимает на его маркер на карте.

Требования

Рекомендуем ознакомиться со следующей документацией:

PlaceSearchElement - Используется для поиска мест поблизости или текстового поиска.
Элемент Place Details – используется для показа информации об отдельном месте.
Maps JavaScript API – используется для показа карты на странице и импорта Places UI Kit.

Включите Maps JavaScript API и Places UI Kit в своем проекте.

Прежде чем начать, убедитесь, что вы загрузили Maps JavaScript API и импортировали необходимые библиотеки. Также предполагается, что вы обладаете базовыми знаниями в области веб-разработки, включая HTML, CSS и JavaScript.

Добавьте карту на страницу

Сначала добавьте на страницу карту. Эта карта будет использоваться для отображения результатов PlaceSearchElement в виде выбираемых маркеров.

Добавить карту на страницу можно двумя способами:

Использование веб-компонента HTML gmp-map.
С помощью JavaScript.

Фрагменты кода на этой странице были созданы с помощью объекта map JavaScript.

Карта может быть центрирована по местоположению, которое вы хотите предложить пользователю для поиска, например по отелю, или по текущему местоположению пользователя. В этом документе мы будем использовать фиксированное местоположение для привязки поиска.

Если вы визуализируете места рядом с фиксированным местоположением, например отелем, поместите на карту маркер, представляющий это место. Пример:

Карта центрирована по Сан-Франциско, а синий маркер указывает на место, рядом с которым мы ищем. Цвет маркера изменен с помощью PinElement. Элемент Тип карты скрыт из интерфейса.

Настройка устройства "`PlaceSearchElement`"

Теперь настройте HTML и CSS для показа PlaceSearchElement. В этом примере элемент размещается в левой части карты, но вы можете попробовать разные макеты, чтобы выбрать наиболее подходящий для вашего приложения.

В PlaceSearchElement используется декларативный подход. Вместо того чтобы полностью настраивать его в JavaScript, вы определяете тип поиска непосредственно в HTML, вкладывая элемент запроса, например <gmp-place-nearby-search-request>, в основной компонент <gmp-place-search>.

Инициализируйте элемент <gmp-place-search> в HTML-коде. Чтобы включить события кликов по результатам, используйте атрибут selectable. Внутри него добавьте <gmp-place-nearby-search-request>, чтобы указать, что этот элемент будет использоваться для поиска поблизости.

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

Чтобы выполнить первоначальный поиск и показать результаты, мы используем JavaScript, чтобы получить ссылку на вложенный элемент запроса и задать его свойства. Инициализируйте объект 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 Nearby Search и Place Types.
<gmp-place-text-search-request> – отображение результатов поиска из текстового поиска мест по запросу, например "Суши в Москве".

Это вложенные элементы внутри <gmp-place-search>. Затем вы запускаете поиск, задавая свойства этого вложенного элемента запроса с помощью JavaScript.

В этом разделе описывается реализация обоих методов.

Поиск поблизости

Чтобы пользователи могли выполнять поиск поблизости, сначала нужно добавить элемент интерфейса, позволяющий выбрать тип места. Выберите метод выбора, который лучше всего подходит для вашего приложения, например раскрывающийся список, заполненный выбранными типами мест.

Рекомендуется выбрать подмножество типов, соответствующих вашему варианту использования. Например, если вы разрабатываете приложение, которое показывает туристам, что находится рядом с отелем, вы можете выбрать: 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>

Затем создайте прослушиватель JavaScript для события 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];
}

Для locationRestriction используется тот же searchCircle, что и на этапе настройки. Свойству includedPrimaryTypes присваивается значение, выбранное пользователем. Также можно задать необязательный параметр maxResultCount, чтобы ограничить количество результатов.

Text Search

Чтобы включить текстовый поиск, необходимо изменить конфигурацию HTML. Вместо запроса на поиск поблизости вы вкладываете элемент <gmp-place-text-search-request>.

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

Добавьте в интерфейс поле для ввода текста и кнопку поиска. Создайте прослушиватель JavaScript для события 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 ограничивает количество возвращаемых результатов.

Показ маркеров мест и сведений о них

Теперь приложение может выполнить поиск мест и заполнить элемент. На следующем шаге мы расширим его функциональность:

Показ маркеров на карте для каждого места, указанного в PlaceSearchElement.
Пользователь может нажать на маркер или место в PlaceSearchElement, чтобы увидеть подробную информацию о нем.

Принцип этого шага одинаков независимо от того, использует ли приложение поиск поблизости или текстовый поиск.

Сначала добавьте в код JavaScript глобальную переменную для хранения маркеров мест. Это позволит вам удалять их при изменении поиска и обрабатывать события кликов.

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:

Теперь, когда на карте есть маркеры, осталось только настроить обработку событий клика по маркеру и элементу, чтобы показывать информационное окно с информацией о местах, которые предоставляет элемент Place Details. В этом примере мы будем использовать компактный элемент информации о местах.

Добавьте 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 передается для отображения всего контента элемента. Чтобы выбрать, какой контент показывать, ознакомьтесь с документацией по компактному элементу информации о местах.

Создайте глобальную переменную в JavaScript, которая будет содержать ссылку на компактный элемент сведений о месте, и заполните ее в коде инициализации, например:

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

Чтобы пользователь мог нажать на место в элементе списка мест и увидеть компактный элемент с информацией о месте, добавьте в код JavaScript после вызова configureFromSearchNearbyRequest следующий фрагмент:

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

После этого приложение сможет использовать поиск поблизости или текстовый поиск, чтобы заполнить элемент списка мест. В результате на карте появятся маркеры. Если нажать на маркер или место в списке, откроется информационное окно с информацией о местах, которые предоставляет элемент Place Details Compact.

Приложение будет выглядеть следующим образом:

Заключение

PlaceSearchElement в сочетании с компактным элементом информации о местах позволяет легко добавлять в приложения на платформе Google Карт функции поиска мест.

Попробуйте Places UI Kit уже сегодня, чтобы ваши пользователи могли находить и изучать места с помощью текстового поиска и поиска поблизости, а также просматривать подробную информацию о местах, улучшая их взаимодействие с вашими вариантами использования поиска мест.

Авторы

Хенрик Вальве (Henrik Valve) | инженер DevX