Wyszukiwarka sklepów z użyciem interfejsu Places UI Kit

Cel

W tym dokumencie opisujemy najważniejsze kroki, które należy wykonać, aby utworzyć interaktywną aplikację do wyszukiwania sklepów za pomocą Google Maps Platform, a konkretnie interfejsu Maps JavaScript API i interfejsu Places UI Kit: elementu Informacje o miejscu. Dowiesz się, jak utworzyć mapę, która wyświetla lokalizacje sklepów, dynamicznie aktualizuje listę widocznych sklepów i wyświetla szczegółowe informacje o każdym sklepie.

Wymagania wstępne

Zalecamy znajomość tych zagadnień:

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

Zanim zaczniesz, sprawdź, czy masz wczytany interfejs Maps JavaScript API i zaimportowane wymagane biblioteki zaawansowanych znaczników i interfejsu Places UI Kit. W tym dokumencie zakładamy też, że masz praktyczną wiedzę na temat tworzenia stron internetowych, w tym języków HTML, CSS i JavaScript.

Konfiguracja początkowa

Najpierw dodaj mapę do strony. Ta mapa będzie używana do wyświetlania pinezek związanych z lokalizacjami Twoich sklepów.

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

  1. użycie komponentu internetowego HTML gmp-map,
  2. Za pomocą JavaScript

Wybierz metodę, która najlepiej odpowiada Twojemu przypadkowi użycia. Oba sposoby implementacji mapy będą działać z tym przewodnikiem.

Wczytywanie i wyświetlanie lokalizacji sklepów

W tej sekcji wczytamy i wyświetlimy dane Twojego sklepu na mapie. W tym przewodniku zakładamy, że masz repozytorium informacji o istniejących sklepach, z którego możesz pobierać dane. Dane o sklepie mogą pochodzić z różnych źródeł, np. z bazy danych. W tym przykładzie zakładamy, że istnieje lokalny plik JSON (stores.json) z tablicą obiektów sklepów, z których każdy reprezentuje jedną lokalizację sklepu. Każdy obiekt powinien zawierać co najmniej name, location (z lat i lng) oraz place_id.

Jeśli nie masz identyfikatorów miejsc dla lokalizacji sklepów, możesz je uzyskać na kilka sposobów. Więcej informacji znajdziesz w dokumentacji dotyczącej identyfikatora miejsca.

Przykładowy wpis ze szczegółami sklepu w pliku stores.json może wyglądać tak: Dostępne są pola Nazwa, Lokalizacja (szer./dł. geogr.) i Identyfikator miejsca. Jest obiekt, który zawiera godziny otwarcia sklepu (skrócone). Są też 2 wartości logiczne, które pomagają opisać niestandardowe cechy lokalizacji sklepu.

{
  "name": "Example Store Alpha",
  "location": { "lat": 51.51, "lng": -0.12 },
  "place_id": "YOUR_STORE_PLACE_ID",
  "opening_hours": { "Monday": "09:00 - 17:00", "...": "..." },
  "new_store_design": true,
  "indoor_seating": false
}

W kodzie JavaScript pobierz dane o lokalizacjach sklepów i wyświetl pinezkę na mapie dla każdej z nich.

Oto przykład, jak to zrobić. Ta funkcja pobiera obiekt zawierający szczegółowe informacje o sklepach i tworzy znacznik na podstawie lokalizacji każdego z nich.

function displayInitialMarkers(storeLocations) {
    if (!AdvancedMarkerElement || !LatLng || !mapElement) return;
    storeLocations.forEach(store => {
        if (store.location) {
            const marker = new AdvancedMarkerElement({
                position: new LatLng(store.location.lat, store.location.lng),
                title: store.name
            });
            mapElement.appendChild(marker);
        }
    });
}

Po wczytaniu sklepów i wyświetleniu na mapie pinezek reprezentujących ich lokalizacje utwórz pasek boczny za pomocą HTML i CSS, aby wyświetlać szczegółowe informacje o poszczególnych sklepach.

Oto przykład, jak może wyglądać lokalizator sklepów na tym etapie:

obraz

Sprawdzanie zmian w widocznym obszarze mapy

Aby zoptymalizować wydajność i wrażenia użytkowników, zaktualizuj aplikację tak, aby wyświetlała znaczniki i szczegóły na pasku bocznym tylko wtedy, gdy odpowiadające im lokalizacje znajdują się w widocznym obszarze mapy (widoku). Obejmuje to nasłuchiwanie zmian widocznego obszaru mapy, eliminowanie efektu drgania styków w przypadku tych zdarzeń, a następnie ponowne rysowanie tylko niezbędnych znaczników.

Dołącz detektor zdarzeń do zdarzenia bezczynności mapy. To zdarzenie jest wywoływane po zakończeniu operacji przesuwania lub powiększania, co zapewnia stabilny widoczny obszar do obliczeń.

map.addListener('idle', debounce(updateMarkersInView, 300));

Powyższy fragment kodu nasłuchuje zdarzenia idle i wywołuje funkcję debounce. Użycie funkcji debounce sprawia, że logika aktualizacji znacznika jest uruchamiana dopiero po krótkiej przerwie w interakcji użytkownika z mapą, co zwiększa wydajność.

function debounce(func, delay) {
    let timeoutId;
    return function(...args) {
        const context = this;
        clearTimeout(timeoutId);
        timeoutId = setTimeout(() => {
            func.apply(context, args);
        }, delay);
    };
}

Powyższy kod to przykładowa funkcja debounce. Przyjmuje funkcję i argument opóźnienia, który można przekazać w detektorze bezczynności. Opóźnienie wynoszące 300 ms wystarczy, aby poczekać, aż mapa przestanie się przesuwać, bez zauważalnego opóźnienia w interfejsie. Po upływie tego czasu wywoływana jest przekazana funkcja, w tym przypadku updateMarkersInView.

Funkcja updateMarkersInView powinna wykonywać te działania:

Usuń wszystkie istniejące znaczniki z mapy

Sprawdź, czy lokalizacja sklepu mieści się w granicach bieżącej mapy, na przykład:

if (map.getBounds().contains(storeLatLng)) {
  // logic
}

W instrukcji if powyżej napisz kod, który wyświetli znaczniki i szczegóły sklepu na pasku bocznym, jeśli lokalizacja sklepu znajduje się w widocznym obszarze mapy.

Wyświetlanie szczegółowych informacji o miejscu za pomocą elementu Szczegóły miejsca

Na tym etapie aplikacja wyświetla wszystkie lokalizacje sklepów, a użytkownicy mogą je filtrować na podstawie widocznego obszaru mapy. Aby ulepszyć tę funkcję, dodajemy szczegółowe informacje o każdym sklepie, takie jak zdjęcia, opinie i informacje o dostępności, za pomocą elementu Szczegóły miejsca. W tym przykładzie użyto kompaktowego elementu ze szczegółowymi informacjami o miejscu.

Każda lokalizacja sklepu w źródle danych musi mieć odpowiadający jej identyfikator miejsca. Ten identyfikator jednoznacznie identyfikuje lokalizację w Mapach Google i jest niezbędny do pobrania jej szczegółów. Zwykle te identyfikatory miejsc są pozyskiwane wcześniej i przechowywane w każdym z rekordów sklepu.

Integracja elementu Informacje o miejscu (kompaktowe) z aplikacją

Gdy sklep zostanie określony jako znajdujący się w bieżącym widoku mapy i będzie renderowany na pasku bocznym, możesz dynamicznie utworzyć i wstawić dla niego kompaktowy element z informacjami o miejscu.

W przypadku aktualnie przetwarzanego sklepu pobierz identyfikator miejsca z danych. Identyfikator miejsca służy do kontrolowania, które miejsce będzie wyświetlane.

W kodzie JavaScript dynamicznie utwórz instancję PlaceDetailsCompactElement. Tworzony jest też nowy obiekt PlaceDetailsPlaceRequestElement, do którego przekazywany jest identyfikator miejsca, a następnie jest on dołączany do obiektu PlaceDetailsCompactElement. Na koniec użyj PlaceContentConfigElement, aby skonfigurować treści, które będą wyświetlane przez element.

Poniższa funkcja zakłada, że niezbędne biblioteki Place UI Kit są zaimportowane i dostępne w zakresie, w którym ta funkcja jest wywoływana, a storeData przekazany do funkcji zawiera place_id.

Ta funkcja zwróci element, a kod wywołujący będzie odpowiedzialny za dołączenie go do DOM.

function createPlaceDetailsCompactElement(storeData) {
    // Create the main details component
    const detailsCompact = new PlaceDetailsCompactElement();
    detailsCompact.setAttribute('orientation', 'vertical'); // Or 'horizontal'

    // Specify the Place ID
    const placeRequest = new PlaceDetailsPlaceRequestElement();
    placeRequest.place = storeData.place_id;
    detailsCompact.appendChild(placeRequest);

    // Configure which content elements to display
    const contentConfig = new PlaceContentConfigElement();
    // For this example, we'll render media, rating, accessibility, and attribution:
    contentConfig.appendChild(new PlaceMediaElement({ lightboxPreferred: true }));
    contentConfig.appendChild(new PlaceRatingElement());
    contentConfig.appendChild(new PlaceAccessibleEntranceIconElement());
    // Configure attribution
    const placeAttribution = new PlaceAttributionElement();
    placeAttribution.setAttribute('light-scheme-color', 'gray');
    placeAttribution.setAttribute('dark-scheme-color', 'gray');
    contentConfig.appendChild(placeAttribution);
    detailsCompact.appendChild(contentConfig);
    // Return the element
    return detailsCompact;
}

W powyższym przykładowym kodzie element jest skonfigurowany tak, aby wyświetlać zdjęcia miejsca, oceny i informacje o ułatwieniach dostępu. Możesz dostosować ten widok, dodając lub usuwając inne dostępne elementy treści. Wszystkie dostępne opcje znajdziesz w dokumentacji PlaceContentConfigElement.

Element kompaktowy ze szczegółowymi informacjami o miejscu obsługuje stylizację za pomocą właściwości niestandardowych CSS. Dzięki temu możesz dostosować jego wygląd (kolory, czcionki itp.) do projektu aplikacji. Zastosuj te właściwości niestandardowe w pliku CSS. Obsługiwane właściwości CSS znajdziesz w dokumentacji PlaceDetailsCompactElement.

Oto przykład, jak może wyglądać Twoja aplikacja na tym etapie:

obraz

Ulepszanie wyszukiwarki sklepów

Masz solidne podstawy, aby utworzyć aplikację do wyszukiwania sklepów. Teraz rozważ kilka sposobów na rozszerzenie jej funkcjonalności i stworzenie jeszcze bogatszego, bardziej zorientowanego na użytkownika środowiska.

Dodaj autouzupełnianie

Ułatw użytkownikom znajdowanie obszarów, w których chcą wyszukiwać sklepy, przez zintegrowanie pola wyszukiwania z autouzupełnianiem miejsc. Gdy użytkownicy wpiszą adres, dzielnicę lub ciekawe miejsce i wybiorą sugestię, zaprogramuj mapę tak, aby automatycznie wyśrodkowała się na tej lokalizacji, co spowoduje aktualizację sklepów w pobliżu. Aby to zrobić, dodaj pole do wprowadzania danych i dołącz do niego funkcję autouzupełniania miejsc. Po wybraniu sugestii mapa może zostać wyśrodkowana w tym punkcie. Pamiętaj, aby skonfigurować go tak, aby faworyzował lub ograniczał wyniki do Twojego obszaru działania.

Wykryj lokalizację

Zapewnij natychmiastową trafność, zwłaszcza użytkownikom urządzeń mobilnych, wdrażając funkcję wykrywania ich bieżącej lokalizacji geograficznej. Po uzyskaniu zgody na wykrywanie lokalizacji w przeglądarce automatycznie wyśrodkuj mapę na pozycji użytkownika i wyświetl najbliższe sklepy. Użytkownicy bardzo cenią sobie funkcję W pobliżu, gdy szukają opcji dostępnych od ręki. Dodaj przycisk lub początkowy prompt, aby poprosić o dostęp do lokalizacji.

Pokaż odległość i wskazówki dojazdu

Gdy użytkownik znajdzie interesujący go sklep, możesz znacznie ułatwić mu dotarcie do niego, integrując interfejs Routes API. W przypadku każdego sklepu na liście oblicz i wyświetl odległość od bieżącej lokalizacji użytkownika lub od wyszukiwanej lokalizacji. Dodatkowo udostępnij przycisk lub link, który używa interfejsu Routes API do wygenerowania trasy z lokalizacji użytkownika do wybranego sklepu. Możesz wyświetlić tę trasę na mapie lub podać link do Map Google, aby umożliwić nawigację, co ułatwi użytkownikom znalezienie sklepu i dotarcie do niego.

Wdrażając te rozszerzenia, możesz korzystać z większej liczby funkcji Google Maps Platform, aby stworzyć bardziej kompleksowy i wygodny lokalizator sklepów, który bezpośrednio odpowiada na typowe potrzeby użytkowników.

Podsumowanie

W tym przewodniku przedstawiliśmy podstawowe kroki tworzenia interaktywnej wyszukiwarki sklepów. Wiesz już, jak wyświetlać lokalizacje własnych sklepów na mapie za pomocą interfejsu Maps JavaScript API, dynamicznie aktualizować widoczne sklepy na podstawie zmian widocznego obszaru oraz, co ważne, jak wyświetlać dane własnych sklepów zgodnie z pakietem Places UI Kit. Korzystając z dotychczasowych informacji o sklepie, w tym identyfikatorów miejsc, oraz elementu Szczegóły miejsca, możesz wyświetlać szczegółowe, ustandaryzowane informacje o każdej lokalizacji, tworząc solidną podstawę dla przyjaznego dla użytkownika lokalizatora sklepów.

Wypróbuj Maps JavaScript API i Places UI Kit, aby oferować zaawansowane narzędzia oparte na komponentach, które umożliwiają szybkie tworzenie zaawansowanych aplikacji opartych na lokalizacji. Łącząc te funkcje, możesz tworzyć angażujące i praktyczne treści dla użytkowników.

Współtwórcy

Henrik Valve | inżynier DevX