Эта страница переведена с помощью Cloud Translation API.

Находите места с помощью элемента поиска мест и API JavaScript Карт

Цель

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

Что такое элемент поиска места?

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

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

На следующем изображении показан пример элемента поиска места в действии. Слева отображается список ресторанов (элемент поиска места). При выборе ресторана информация о нём отображается в информационном окне на карте, а карта центрируется на его местоположении.

Примеры использования обнаружения мест

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

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

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

В этом разделе описывается, как интегрировать элемент поиска мест на карте, включая фрагменты кода для взаимодействия с Places UI Kit. Мы рассмотрим инициализацию карты и реализацию функций поиска поблизости и текстового поиска. Наконец, мы используем элемент «Сведения о месте», чтобы отображать более подробную информацию о конкретном месте при щелчке по его метке на карте.

Предпосылки

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

Элемент поиска места — используется для отображения мест с помощью поиска поблизости или текстового поиска.
Элемент «Сведения о месте» — используется для отображения сведений об отдельном месте.
Maps JavaScript API — используется для отображения карты на вашей странице и для импорта Places UI Kit.

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

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

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

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

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

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

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

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

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

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

Настроить элемент поиска места

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

Элемент поиска места использует декларативный подход. Вместо того, чтобы полностью настраивать его в JavaScript, вы определяете тип поиска непосредственно в 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>

Для выполнения первоначального поиска и отображения результатов мы используем 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'];

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

Разрешить пользователю искать

Элемент поиска места допускает два варианта поиска:

<gmp-place-nearby-search-request> — отображает результаты поиска из Places Nearby Search с использованием Place Types .
<gmp-place-text-search-request> — отображает результаты поиска по тексту Places , используя свободное текстовое поле, например «Суши в Сан-Франциско».

Это вложенные элементы внутри <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 для ограничения количества результатов.

Текстовый поиск

Чтобы включить текстовый поиск, необходимо изменить 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 ограничивает количество возвращаемых результатов.

Отображение пинов и подробностей места

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

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

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

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

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 . В этом примере мы будем использовать компактный элемент 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 . Чтобы выбрать, какое содержимое отображать, см. документацию по компактному элементу Place Details .

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

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

В функции addMarkers добавьте прослушиватель событий gmp-click к каждому маркеру и настройте компактный элемент Place Details для отображения сведений о месте, передав идентификатор места текущего маркера.

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

Наконец, карта размещается в области просмотра выбранного места, делая его видимым.

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

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

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

Заключение

Элемент поиска места в сочетании с компактным элементом сведений о месте обеспечивает упрощенный способ добавления расширенных функций поиска места в ваши приложения платформы Google Карт.

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

Авторы

Хенрик Валв | Инженер DevX