Odkrywanie miejsc za pomocą elementu wyszukiwania miejsc i interfejsu Maps JavaScript API

Cel

Dowiedz się, jak zintegrować element wyszukiwania miejsca z Mapami Google, aby ułatwić użytkownikom znajdowanie miejsc za pomocą wyszukiwania w pobliżu lub wyszukiwania tekstowego, co zwiększy ich możliwości odkrywania interesujących miejsc. Użyj kompaktowego elementu szczegółów miejsca, aby podać więcej informacji o miejscach wyświetlanych w aplikacji.

Czym jest element Wyszukiwanie miejsc?

Element wyszukiwania miejsca jest częścią interfejsu Places UI Kit w interfejsie Maps JavaScript API. Jest to element HTML, który renderuje wyniki wyszukiwania miejsca bezpośrednio w formacie listy w aplikacji. Ten element upraszcza proces wyświetlania miejsc znalezionych za pomocą wyszukiwania w pobliżu lub wyszukiwania tekstowego, zapewniając użytkownikom płynne działanie podczas odkrywania miejsc. Gdy użytkownik wybierze miejsce z listy, możesz wyświetlić jego szczegóły na mapie, często za pomocą okna informacyjnego i elementu szczegółów miejsca.

Wizualizacja odkrywania miejsc

Obraz poniżej przedstawia przykład działania elementu wyszukiwania miejsca. Po lewej stronie wyświetla się lista restauracji (element wyszukiwania miejsc). Po wybraniu restauracji jej szczegóły pojawią się w oknie informacyjnym na mapie, a mapa zostanie wyśrodkowana na jej lokalizacji.

obraz

Przypadki użycia odkrywania miejsc

Integracja elementu wyszukiwania miejsca może usprawnić różne aplikacje w różnych branżach:

  • Turystyka: umożliwia turystom wyszukiwanie atrakcji, hoteli lub określonych rodzajów kuchni w danym regionie.
  • Nieruchomości: umożliwiaj potencjalnym kupującym lub wynajmującym znajdowanie w pobliżu szkół, supermarketów lub opcji transportu publicznego.
  • Logistyka i usługi: pomoc kierowcom w znajdowaniu stacji ładowania pojazdów elektrycznych, stacji benzynowych lub konkretnych centrów serwisowych.

Przepływ pracy związany z wdrażaniem rozwiązania: wdrażanie odkrywania miejsc

W tej sekcji znajdziesz instrukcje integracji elementu wyszukiwania miejsc do odkrywania miejsc na mapie, w tym fragmenty kodu do interakcji z zestawem interfejsu Miejsc. Omówimy inicjowanie mapy oraz wdrażanie funkcji wyszukiwania w pobliżu i wyszukiwania tekstowego. Na koniec użyjemy elementu PlaceDetails, aby wyświetlić więcej szczegółów o danym miejscu po kliknięciu jego pinezki na mapie.

Wymagania wstępne

Zalecamy zapoznanie się z tymi dokumentami:

Włącz w projekcie interfejs Maps JavaScript API i interfejs Places UI Kit.

Zanim zaczniesz, sprawdź, czy interfejs Maps JavaScript API został wczytany i czy zaimportowano wymagane biblioteki. Zakładamy też, że masz praktyczną znajomość tworzenia stron internetowych, w tym języków HTML, CSS i JavaScript.

Dodawanie mapy do strony

Najpierw dodaj mapę do strony. Ta mapa będzie używana do wyświetlania wyników wyszukiwania miejsc w postaci pinezek, które można wybrać.

Mapę możesz dodać do strony na 2 sposoby:

  1. Używanie gmp-map komponentu internetowego HTML.
  2. za pomocą JavaScript;

Fragmenty kodu na tej stronie zostały wygenerowane przy użyciu mapy JavaScript.

Mapa może być wyśrodkowana na lokalizacji, w której użytkownik ma wyszukiwać, np. na hotelu, lub może być zainicjowana tak, aby prosić o bieżącą lokalizację użytkownika w celu wyśrodkowania mapy. Na potrzeby tego dokumentu użyjemy stałej lokalizacji, aby zakotwiczyć wyszukiwanie.

Jeśli wizualizujesz miejsca w pobliżu stałej lokalizacji, np. hotelu, umieść na mapie znacznik, aby przedstawić to miejsce. Na przykład:

obraz

Mapa jest wyśrodkowana na San Francisco. Niebieska pinezka oznacza miejsce, w pobliżu którego szukamy. Kolor pinezki został dostosowany za pomocą elementu PinElement. Element sterujący typem mapy został ukryty w interfejsie.

Konfigurowanie elementu Wyszukiwanie miejsc

Teraz możemy skonfigurować kod HTML i CSS, aby wyświetlić element wyszukiwania miejsc. W tym przykładzie umieścimy element po lewej stronie mapy, ale zalecamy wypróbowanie różnych układów, aby dopasować je do swojej aplikacji.

Element wyszukiwania miejsca korzysta z podejścia deklaratywnego. Zamiast konfigurować go w całości w JavaScript, możesz zdefiniować typ wyszukiwania bezpośrednio w HTML, zagnieżdżając element żądania, np. <gmp-place-nearby-search-request>, w głównym komponencie <gmp-place-search>.

W kodzie HTML zainicjuj element <gmp-place-search>. Użyj atrybutu selectable, aby włączyć zdarzenia kliknięcia w wynikach. W tym elemencie dodaj element <gmp-place-nearby-search-request>, aby określić, że będzie on używany do wyszukiwania w pobliżu.

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

Aby przeprowadzić wstępne wyszukiwanie i wyświetlić wyniki, użyjemy JavaScriptu, aby uzyskać odwołanie do zagnieżdżonego elementu żądania i ustawić jego właściwości. Zainicjuj obiekt Circle, który będzie używany jako locationRestriction, używając pozycji znacznika z poprzedniego kroku jako punktu środkowego. Następnie ustaw właściwości locationRestriction i includedPrimaryTypes w elemencie żądania, aby wywołać wyszukiwanie.

Fragment kodu wygląda tak:

// 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'];

Przykład tego, jak aplikacja może wyglądać na tym etapie:

obraz

Element Wyszukiwanie miejsc umożliwia 2 opcje wyszukiwania:

Są to zagnieżdżone elementy w <gmp-place-search>. Następnie możesz wywoływać wyszukiwania, ustawiając właściwości w tym zagnieżdżonym elemencie żądania za pomocą JavaScriptu.

W tej sekcji opisujemy wdrażanie obu metod.

obraz

Aby umożliwić użytkownikom wyszukiwanie w pobliżu, musisz najpierw udostępnić im element interfejsu, w którym będą mogli wybrać typ miejsca. Wybierz metodę wyboru, która najlepiej pasuje do Twojej aplikacji, np. listę rozwijaną wypełnioną wybranymi typami miejsc.

Zalecamy wybranie podzbioru typów, które są istotne w Twoim przypadku użycia. Jeśli na przykład tworzysz aplikację, która ma pokazywać turystom, co znajduje się w pobliżu hotelu, możesz wybrać te interfejsy API: bakery, coffee_shop, museum, restaurant i tourist_attraction.

Kod HTML powinien zawierać element <gmp-place-search> z elementem <gmp-place-nearby-search-request> zagnieżdżonym w nim.

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

Następnie utwórz odbiornik JavaScript dla zdarzenia change w selektorze typu miejsca. Ten odbiornik wywoła funkcję, która zaktualizuje właściwości elementu <gmp-place-nearby-search-request>, co automatycznie spowoduje nowe wyszukiwanie i zaktualizowanie listy.

// 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];
}

W przypadku parametru locationRestriction używana jest ta sama wartość searchCircle co w kroku konfiguracji. Właściwość includedPrimaryTypes jest ustawiona na wartość wybraną przez użytkownika. Opcjonalny parametr maxResultCount jest też ustawiony, aby ograniczyć liczbę wyników.

Wyszukaj tekst

obraz

Aby włączyć wyszukiwanie tekstu, musisz zmienić konfigurację HTML. Zamiast żądania wyszukiwania w pobliżu zagnieżdżasz element <gmp-place-text-search-request>.

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

Dodaj do interfejsu pole tekstowe i przycisk wyszukiwania. Utwórz detektor JavaScript dla zdarzenia click przycisku. Procedura obsługi zdarzeń przyjmie dane wejściowe użytkownika i zaktualizuje właściwości elementu <gmp-place-text-search-request>, aby przeprowadzić wyszukiwanie.

// 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;
}

W tym przypadku ustawiamy właściwość textQuery na podstawie danych wprowadzonych przez użytkownika. Podajemy też parametr locationBias, który wykorzystuje bieżące granice mapy i informuje interfejs API, że ma preferować wyniki w tym obszarze, ale nie ogranicza ich ściśle. Opcjonalny parametr maxResultCount ogranicza liczbę zwracanych wyników.

Wyświetlanie pinezek i szczegółów miejsc

Aplikacja może teraz wyszukiwać miejsca i wypełniać element. W kolejnym kroku rozszerzymy jego funkcjonalność, wykonując te działania:

  • Wyświetlanie pinezek na mapie dla każdego miejsca wypełnionego w elemencie wyszukiwania miejsca.
  • Umożliwienie użytkownikowi kliknięcia pinezki lub miejsca w elemencie wyszukiwania miejsc, aby wyświetlić więcej szczegółów o danym miejscu.

Zasada tego kroku jest taka sama niezależnie od tego, czy aplikacja korzysta z wyszukiwania w pobliżu, czy z wyszukiwania tekstowego.

Najpierw dodaj do kodu JavaScript globalną zmienną, w której będą przechowywane znaczniki miejsca. Dzięki temu będziesz mieć możliwość usuwania ich, gdy zmieni się wyszukiwanie, i obsługiwania zdarzeń kliknięcia.

let markers = {};

Utwórz funkcję dodawania znaczników do mapy. Ta funkcja będzie wywoływana za każdym razem, gdy wczytywane będą nowe wyniki wyszukiwania. Spowoduje to:

  • Usuń z mapy wszystkie istniejące znaczniki miejsc.
  • Przejdź w pętli przez wyniki z elementu wyszukiwania miejsca i dodaj znacznik dla każdego z nich.
  • Dostosuj granice mapy, aby wszystkie nowe znaczniki były widoczne.

Aby nasłuchiwać, kiedy wyniki wyszukiwania są dostępne, dodaj detektor zdarzeń gmp-load do elementu <gmp-place-search>. To zdarzenie jest wywoływane po zakończeniu wyszukiwania i wyświetleniu wyników.

Dodamy detektor w funkcji wyszukiwania (np. updatePlaceList), a następnie użyj opcji { once: true }, aby mieć pewność, że będzie się ona uruchamiać tylko w przypadku wyników bieżącego wyszukiwania.

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

Funkcja addMarkers wygląda tak:

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

Po wykonaniu tego kroku aplikacja będzie wyglądać tak jak poniżej. Będzie można w niej wyświetlać markery dla każdego miejsca zwróconego przez element wyszukiwania miejsc:

obraz

Teraz, gdy mamy już znaczniki na mapie, ostatnim krokiem jest obsługa zdarzeń kliknięcia znacznika i elementu, aby wyświetlić okno informacyjne ze szczegółami miejsca dostarczonymi przez element szczegółów miejsca. W tym przykładzie użyjemy kompaktowego elementu szczegółów miejsca.

Dodaj do kodu HTML element kompaktowy ze szczegółami miejsca, np.:

<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>

Wartość style jest ustawiona na display: none. Nie będzie widoczna, dopóki nie będzie wymagana. gmp-place-all-content jest przekazywany w celu wyrenderowania całej zawartości elementu. Aby wybrać, które treści mają być renderowane, zapoznaj się z dokumentacją komponentu Place Details Compact.

Utwórz w JavaScript globalną zmienną, która będzie przechowywać odwołanie do kompaktowego elementu szczegółów miejsca, i wypełnij ją w kodzie inicjującym, np.:

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

W funkcji addMarkers dodaj do każdego znacznika gmp-click detektor zdarzeń i skonfiguruj kompaktowy element szczegółów miejsca, aby wyświetlał szczegóły miejsca, przekazując identyfikator miejsca bieżącego znacznika.

Gdy to zrobisz, otworzy się okno informacyjne z kompaktowym elementem szczegółów miejsca, który będzie przytwierdzony do znacznika.

Na koniec mapa jest pozycjonowana w obszarze widoku wybranego miejsca, dzięki czemu jest widoczna.

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

Aby umożliwić użytkownikowi kliknięcie miejsca w elemencie listy miejsc i wyświetlenie elementu kompaktowego szczegółów miejsca, dodaj do kodu JavaScript po wywołaniu funkcji configureFromSearchNearbyRequest ten kod:

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

Po wykonaniu tego kroku aplikacja będzie mogła używać wyszukiwania w pobliżu lub wyszukiwania tekstowego do wypełniania elementu listy miejsc. Wyniki tej operacji będą wyświetlane na mapie w postaci pinezek. Kliknięcie pinezki lub miejsca na liście miejsc spowoduje wyświetlenie okna informacyjnego ze szczegółami miejsca, które są dostarczane przez element kompaktowy szczegółów miejsca.

Aplikacja będzie wyglądać tak:

obraz

Podsumowanie

Element wyszukiwania miejsca w połączeniu z elementem szczegółów miejsca w wersji kompaktowej zapewnia uproszczony sposób dodawania do aplikacji Google Maps Platform zaawansowanych funkcji wyszukiwania miejsc.

Wypróbuj już dziś Places UI Kit, aby umożliwić użytkownikom wyszukiwanie i odkrywanie miejsc za pomocą wyszukiwania w pobliżu i wyszukiwania tekstowego oraz wyświetlanie szczegółowych informacji o miejscach, co zwiększy ich interakcję z Twoimi przypadkami użycia związanymi z odkrywaniem miejsc.

Współtwórcy

Henrik Valve | Inżynier DevX