Odkrywanie miejsc za pomocą elementu PlaceSearchElement

Cel

Dowiedz się, jak zintegrować PlaceSearchElement z Mapami Google, aby ułatwić użytkownikom wyszukiwanie miejsc w pobliżu lub za pomocą 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.

Co to jest PlaceSearchElement?

PlaceSearchElement jest częścią interfejsu Places UI Kit w 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 informacji o miejscu.

Wizualizacja odkrywania miejsc

Na ilustracji poniżej widać przykład działania PlaceSearchElement. Po lewej stronie wyświetla się lista restauracji (PlaceSearchElement). Po wybraniu restauracji jej szczegóły pojawiają się w oknie informacyjnym na mapie, a mapa jest wyśrodkowana na jej lokalizacji.

obraz

Przypadki użycia odkrywania miejsc

Integracja PlaceSearchElement 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: pomagaj kierowcom w znajdowaniu stacji ładowania pojazdów elektrycznych, stacji benzynowych lub konkretnych centrów serwisowych.

Przepływ pracy rozwiązania: wdrażanie odkrywania miejsc

W tej sekcji znajdziesz informacje o integracji PlaceSearchElement, która umożliwia odkrywanie miejsc na mapie. Zawiera ona też fragmenty kodu do interakcji z interfejsem Places UI Kit. Dowiedz się, jak zainicjować mapę i wdrożyć wyszukiwanie w pobliżu oraz wyszukiwanie tekstowe. Na koniec użyj elementu Szczegóły miejsca, aby wyświetlić więcej informacji o miejscu, gdy użytkownik kliknie jego pinezkę na mapie.

Wymagania wstępne

Zalecamy zapoznanie się z tymi dokumentami:

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

Zanim zaczniesz, sprawdź, czy interfejs Maps JavaScript API został wczytany i czy zaimportowano wymagane biblioteki. Zakładamy też, że masz praktyczną wiedzę na temat tworzenia stron internetowych, w tym HTML, CSS i JavaScript.

Dodawanie mapy do strony

Pierwszym krokiem jest dodanie mapy do strony. Ta mapa będzie używana do wyświetlania wyników elementu PlaceSearchElement 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 marker, aby przedstawić to miejsce. Na przykład:

obraz

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

Skonfiguruj PlaceSearchElement

Teraz skonfiguruj kod HTML i CSS, aby wyświetlać PlaceSearchElement. Ten przykład powoduje umieszczenie elementu po lewej stronie mapy, ale możesz wypróbować różne układy, aby dopasować je do swojej aplikacji.

PlaceSearchElement 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. Dodaj do niego element <gmp-place-nearby-search-request>, aby określić, że ten element będzie 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ładowy wygląd aplikacji na tym etapie:

obraz

PlaceSearchElement umożliwia wyszukiwanie na 2 sposoby:

Są to elementy zagnieżdżone w <gmp-place-search>. Następnie możesz wywoływać wyszukiwania, ustawiając właściwości tego zagnieżdżonego elementu żą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ą wyborem typów 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ć: bakery, coffee_shop, museum, restaurant i tourist_attraction.

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

<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. Możesz też ustawić opcjonalny parametr maxResultCount, 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 do wprowadzania tekstu i przycisk wyszukiwania. Utwórz odbiornik JavaScript dla zdarzenia click przycisku. Moduł obsługi zdarzeń pobierze 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. Udostępniamy 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 czynności:

  • Wyświetlanie pinezek na mapie dla każdego miejsca wypełnionego w PlaceSearchElement.
  • Umożliwienie użytkownikowi kliknięcia pinezki lub miejsca w PlaceSearchElement, 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. Będzie on:

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

Aby nasłuchiwać, kiedy dostępne są wyniki wyszukiwania, 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 odbiornik w funkcji wyszukiwania (np. updatePlaceList) i użyjemy opcji { once: true }, aby mieć pewność, że będzie on wywoływany 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 PlaceSearchElement:

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 informacjami o miejscu dostarczonymi przez element informacji o miejscu. W tym przykładzie użyjemy kompaktowego elementu informacji o miejscu.

Dodaj do kodu HTML kompaktowy element informacji o miejscu, 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 informacji o miejscu, 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, w którym wyświetli się kompaktowy element informacji o miejscu zakotwiczony na znaczniku.

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 na liście miejsc i wyświetlenie kompaktowego elementu 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 tego działania 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 jest dostarczane przez element kompaktowy szczegółów miejsca.

Aplikacja będzie wyglądać tak:

obraz

Podsumowanie

PlaceSearchElement w połączeniu z kompaktowym elementem informacji o miejscu zapewnia uproszczony sposób dodawania do aplikacji Google Maps Platform zaawansowanych funkcji odkrywania 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