Tworzenie interaktywnego lokalizatora sklepów za pomocą pakietu UI do Miejsc

Cel

W tym dokumencie znajdziesz najważniejsze kroki tworzenia interaktywnej aplikacji do wyszukiwania sklepów za pomocą Google Maps Platform, a w szczególności interfejsu Maps JavaScript API i interfejsu Places UI Kit: elementu szczegółów miejsca. Dowiesz się, jak utworzyć mapę, na której będą wyświetlane lokalizacje sklepów, dynamicznie aktualizować listę widocznych sklepów i wyświetlać szczegółowe informacje o każdym sklepie.

Wymagania wstępne

Zalecana jest znajomość tych zagadnień:

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

Zanim zaczniesz, sprawdź, czy załadowano interfejs Maps JavaScript API i zaimportowano wymagane biblioteki zaawansowanych znaczników i interfejsu Places UI Kit. Zakładamy też, że masz praktyczną znajomość 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żywanie komponentu internetowego HTML gmp-map
  2. Korzystanie z JavaScript

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

Prezentacja

Ta wersja demonstracyjna pokazuje przykład działania wyszukiwarki sklepów, która wyświetla lokalizacje biur Google w obszarze Zatoki San Francisco. Element szczegółów miejsca jest wyświetlany dla każdej lokalizacji wraz z przykładowymi atrybutami.

Wczytywanie i wyświetlanie lokalizacji sklepów

W tej sekcji wczytamy i wyświetlimy dane sklepu na mapie. W tym przewodniku zakładamy, że masz repozytorium informacji o istniejących sklepach, z którego możesz korzystać. Dane o sklepie mogą pochodzić z różnych źródeł, np. z bazy danych. W tym przykładzie zakładamy, że mamy lokalny plik JSON (stores.json) z tablicą obiektów sklepu, 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 jeszcze identyfikatorów miejsc dla lokalizacji sklepów, możesz je uzyskać na różne sposoby. 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: Zawiera pola Nazwa, Lokalizacja (szerokość/długość geograficzna) i Identyfikator miejsca. Jest obiekt zawierający godziny otwarcia sklepu (skrócone). Dostępne są też 2 wartości logiczne, które pomagają opisać niestandardowe funkcje 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 przyjmuje obiekt zawierający szczegóły dotyczące sklepów 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óły poszczególnych sklepów.

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

obraz

Nasłuchiwanie zmian widocznego obszaru mapy

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

Dołącz odbiornik zdarzeń do zdarzenia idle mapy. To zdarzenie jest wywoływane po zakończeniu wszystkich operacji przesuwania lub powiększania, co zapewnia stabilny widok do obliczeń.

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

Powyższy fragment kodu nasłuchuje zdarzenia idle i wywołuje funkcję debounce. Funkcja debounce zapewnia, że logika aktualizacji znacznika jest uruchamiana tylko wtedy, gdy użytkownik przez krótki czas nie wchodzi w interakcje 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óre można zobaczyć w przekazywaniu do detektora bezczynności. Opóźnienie 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:

Usuwanie wszystkich istniejących znaczników z mapy

Sprawdź, czy lokalizacja sklepu mieści się w bieżących granicach mapy, np.:

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

W instrukcji if powyżej napisz kod, który wyświetli markery 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ółów miejsca

Na tym etapie aplikacja wyświetla wszystkie lokalizacje sklepów, a użytkownicy mogą je filtrować na podstawie widoku mapy. Aby to ulepszyć, dodajemy szczegółowe informacje o każdym sklepie, takie jak zdjęcia, opinie i informacje o dostępności, za pomocą elementu szczegółów miejsca. W tym przykładzie użyto elementu Place Details Compact Element.

Każda lokalizacja sklepu w źródle danych musi mieć odpowiedni identyfikator miejsca. Ten identyfikator jednoznacznie identyfikuje lokalizację w Mapach Google i jest niezbędny do pobierania jej szczegółów. Identyfikatory miejsc są zwykle pozyskiwane z wyprzedzeniem i przechowywane w rekordach poszczególnych sklepów.

Integrowanie w aplikacji kompaktowego elementu Informacje o miejscu

Gdy sklep znajduje się w bieżącym widoku mapy i jest renderowany na pasku bocznym, możesz dynamicznie utworzyć i wstawić dla niego kompaktowy element szczegółów miejsca.

Pobierz identyfikator miejsca z danych bieżącego przetwarzanego sklepu. Identyfikator miejsca służy do określania, w którym miejscu będzie wyświetlany element.

W 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 elementu PlaceContentConfigElement, aby skonfigurować treść, która będzie wyświetlana w tym elemencie.

Poniższa funkcja zakłada, że niezbędne biblioteki Place UI Kit są zaimportowane i dostępne w zakresie, w którym jest wywoływana, a storeData przekazane 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 przykładzie kodu powyżej element jest skonfigurowany tak, aby wyświetlać zdjęcia miejsca, ocenę w opinii 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 PlaceContentConfigElement dokumentacji.

Kompaktowy element szczegółów miejsca obsługuje stylizację za pomocą niestandardowych właściwości 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 referencyjnej elementu PlaceDetailsCompactElement.

Przykład, jak może wyglądać Twoje zgłoszenie na tym etapie:

obraz

Ulepszanie lokalizatora sklepów

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

Dodaj autouzupełnianie

Ułatw użytkownikom znajdowanie obszarów, w których mogą wyszukiwać sklepy, integrując pole wyszukiwania z autouzupełnianiem miejsc. Gdy użytkownicy wpiszą adres, dzielnicę lub ciekawe miejsce i wybiorą sugestię, zaprogramuj mapę tak, aby automatycznie wyśrodkowywała się w tej lokalizacji, co spowoduje aktualizację pobliskich sklepów. Aby to zrobić, dodaj pole 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łalności.

Wykrywanie lokalizacji

Zapewnij natychmiastową trafność, zwłaszcza w przypadku użytkowników urządzeń mobilnych, wdrażając funkcję wykrywania ich bieżącej lokalizacji geograficznej. Po uzyskaniu od przeglądarki uprawnień do wykrywania lokalizacji użytkownika automatycznie wyśrodkuj mapę na jego pozycji 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 z prośbą 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 podróż, integrując Routes API. W przypadku każdego wymienionego sklepu oblicz i wyświetl odległość od bieżącej lokalizacji użytkownika lub od wyszukiwanej lokalizacji. Dodatkowo udostępnij przycisk lub link, który korzysta z interfejsu Routes API, aby wygenerować trasę z lokalizacji użytkownika do wybranego sklepu. Możesz wtedy wyświetlić tę trasę na mapie lub utworzyć link do Map Google, aby uzyskać wskazówki dojazdu. Dzięki temu przejście od znalezienia sklepu do dotarcia do niego będzie płynne.

Wdrażając te rozszerzenia, możesz korzystać z większej liczby funkcji Platformy Google Maps, aby tworzyć bardziej kompleksowe i wygodne lokalizatory sklepów, które bezpośrednio odpowiadają na typowe potrzeby użytkowników.

Podsumowanie

W tym przewodniku przedstawiliśmy podstawowe kroki tworzenia interaktywnej wyszukiwarki sklepów. Dowiedziałeś się, jak wyświetlać lokalizacje własnych sklepów na mapie za pomocą interfejsu Maps JavaScript API, dynamicznie aktualizować widoczne sklepy na podstawie zmian w obszarze widoku oraz, co najważniejsze, jak wyświetlać własne dane o sklepach zgodnie z zestawem interfejsu Places UI Kit. Korzystając z dotychczasowych informacji o sklepie, w tym identyfikatorów miejsc, w połączeniu z elementem szczegółów miejsca, możesz wyświetlać bogate, standardowe informacje o każdej z Twoich lokalizacji, tworząc solidną podstawę dla przyjaznej dla użytkownika wyszukiwarki sklepów.

Wypróbuj interfejs Maps JavaScript API i interfejs 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 informacyjne treści dla użytkowników.

Współtwórcy

Henrik Valve | Inżynier DevX