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

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

Цель

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

Что представляет собой элемент поиска мест?

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

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

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

Примеры использования для поиска мест

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

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

Процесс внедрения решения: реализация метода поиска мест

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

Предварительные требования

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

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

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

Перед началом работы убедитесь, что вы загрузили 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> - отображает результаты поиска по запросу "Места поблизости" , используя типы мест .
<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 для ограничения количества результатов.

Поиск текста

Для включения текстового поиска необходимо изменить конфигурацию 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);
    }
}

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

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

Добавьте в свой код 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();
    }
});

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

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

Заключение

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

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

Авторы

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