Zastosowanie pakietu UI do Miejsc przez dotychczasowych użytkowników interfejsu Places API

Dowiedz się, jak przenieść dotychczasową implementację Places API lub klasy Place do komponentów Places UI Kit.

Komu przyda się ten przewodnik

Ten przewodnik jest przeznaczony dla deweloperów, którzy mają już implementację korzystającą z Places API i chcą zaktualizować kod, aby używać Places UI Kit. Najbardziej przydatne będzie, jeśli:

  • wysyłanie żądań HTTP do punktów końcowych interfejsu Places API (nowego lub starszego);
  • użycie klasy Place w interfejsie Maps JavaScript API;
  • obsługę odpowiedzi interfejsu API w celu renderowania informacji o miejscu w interfejsie aplikacji internetowej.

Wymagania wstępne

Włącz Places UI Kit w projekcie Google Cloud. Możesz nadal używać dotychczasowego klucza interfejsu API lub wygenerować nowy klucz dla Places UI Kit. Więcej informacji, w tym o ograniczaniu klucza, znajdziesz w artykule Używanie kluczy interfejsu API.

Aktualizowanie wczytywania interfejsu Maps JavaScript API

Interfejs Places UI Kit wymaga metody wczytywania interfejsu Maps JavaScript API Dynamic Library Import. Jeśli używasz tagu bezpośredniego wczytywania skryptu, musisz go zaktualizować.

Po zaktualizowaniu skryptu wczytywania interfejsu Maps JavaScript API zaimportuj wymagane biblioteki, aby korzystać z interfejsu Places UI Kit.

Implementowanie elementu informacji o miejscu

Element informacji o miejscu i element informacji o miejscu (kompaktowy) to elementy HTML, które renderują informacje o miejscu.

Obecne wdrożenie

  • Wywołujesz informacje o miejscu za pomocą żądania HTTP lub używasz klasy Place interfejsu JavaScript API.
  • Przeanalizuj odpowiedź interfejsu API i wyświetl szczegóły miejsca za pomocą kodu HTML i CSS.

Migracja do elementu Informacje o miejscu

Modyfikowanie struktury HTML

Zidentyfikuj kontener HTML, w którym są renderowane informacje o miejscu. Zastąp niestandardowe elementy HTML (div, span dla nazwy, adresu, zdjęć itp.) elementem HTML z informacjami o miejscu.

Do wyboru są 2 elementy:

  • Element kompaktowy informacji o miejscu
  • Element informacji o miejscu

Więcej informacji o tym, którego elementu użyć, znajdziesz w artykule Element informacji o miejscu.

Dotychczasowy kod HTML może wyglądać tak:

<div id="my-place-details-container">
    <h2 id="place-name"></h2>
    <p id="place-address"></p>
    <img id="place-photo" src="" alt="Place photo">
    <!-- ... more custom elements -->
</div>

Przykład nowego kodu HTML, który wyraźnie określa, jakie treści mają być wyświetlane:

<gmp-place-details-compact orientation="horizontal" truncation-preferred style="display: none;">
    <gmp-place-details-place-request></gmp-place-details-place-request>
    <gmp-place-content-config>
        <gmp-place-media lightbox-preferred></gmp-place-media>
        <gmp-place-address></gmp-place-address>
        <gmp-place-rating></gmp-place-rating>
        <gmp-place-type></gmp-place-type>
        <gmp-place-price></gmp-place-price>
        <gmp-place-accessible-entrance-icon></gmp-place-accessible-entrance-icon>
        <gmp-place-open-now-status></gmp-place-open-now-status>
    </gmp-place-content-config>
</gmp-place-details-compact>

Dostosowywanie logiki JavaScriptu

Istniejąca logika

Dotychczasowa logika prawdopodobnie obejmuje:

  • pobieranie identyfikatora miejsca,
  • użycie PlacesService().getDetails() lub wywołanie usługi internetowej;
  • określenie tablicy pól (w przypadku interfejsu JS API) lub maski FieldMask (w przypadku usługi internetowej) w celu żądania konkretnych danych;
  • W rozwiązaniu wywołania zwrotnego ręcznie wybierz elementy HTML i wypełnij je otrzymanymi danymi.

Oto przykład implementacji informacji o miejscu:

async function getPlaceDetails(placeId) {
    const { Place } = await google.maps.importLibrary('places');
    // Use place ID to create a new Place instance.
    const place = new Place({
        id: placeId
    });
    await place.fetchFields({
        fields: ['displayName', 'formattedAddress', 'location'],
    });
    // Log the result
    console.log(place.displayName);
    console.log(place.formattedAddress);
}
Nowa logika

Nowa logika będzie obejmować:

  • Pobierz identyfikator miejsca lub obiekt miejsca.
  • Pobierz odwołanie do elementu <gmp-place-details-place-request>.
  • Przekaż identyfikator miejsca lub obiekt miejsca do właściwości miejsca w elemencie <gmp-place-details-place-request>.

Poniżej znajdziesz przykład implementacji pakietu UI informacji o miejscu w logice JavaScriptu. Uzyskaj odwołanie do elementu Szczegóły miejsca. Jeśli istnieje, pobierz odwołanie do elementu żądania miejsca w informacjach o miejscu i ustaw właściwość miejsca za pomocą identyfikatora miejsca. W powyższym przykładowym kodzie HTML styl elementu Szczegóły miejsca jest ustawiony na display: none. Zaktualizowano do: display: block.

function displayPlaceDetailsWithUIKit(placeId) {
  const placeDetailsElement = document.querySelector('gmp-place-details-compact');
  if (placeDetailsElement) {
    const placeDetailsRequest = document.querySelector('gmp-place-details-place-request');
    // Configure the element with the Place ID
    placeDetailsRequest.place = placeId
    placeDetailsElement.style.display = 'block';
    console.log("PlaceDetailsElement configured for place:", placeId);
  } else {
    console.error("PlaceDetailsElement not found in the DOM.");
  }
}

// Example usage:
const placeId = 'ChIJC8HakaIRkFQRiOgkgdHmqkk';
displayPlaceDetailsWithUIKit(placeId);

Element wyszukiwania miejsc to element HTML, który wyświetla wyniki wyszukiwania miejsc w postaci listy.

  • Wykonujesz wyszukiwanie tekstu lub wyszukiwanie w pobliżu za pomocą żądania HTTP albo używasz klasy Place interfejsu JavaScript API.
  • Parametry zapytania, ograniczenia lub preferencje dotyczące lokalizacji, typy i żądane pola określasz za pomocą parametru FieldMask.
  • Przeanalizujesz odpowiedź interfejsu API, przejdziesz przez tablicę miejsc i ręcznie utworzysz elementy listy HTML.

Modyfikowanie struktury HTML

Zidentyfikuj kontener HTML, w którym renderujesz listę Twoich miejsc. Zastąp niestandardowe elementy HTML (div, span dla nazwy, adresu itp.) elementem HTML wyszukiwania miejsc.

Istniejący kod HTML może wyglądać mniej więcej tak:

<div id="search-results-area">
    <h3>Nearby Places:</h3>
    <ul id="manual-places-list">
        <!-- JavaScript would dynamically insert list items here -->
        <!-- Example of what JS might generate:
    <li class="place-entry" data-place-id="SOME_PLACE_ID_1">
      <img class="place-icon" src="icon_url_1.png" alt="Icon">
      <span class="place-name">Place Name One</span> -
      <span class="place-vicinity">123 Main St</span>
    </li>
    <li class="place-entry" data-place-id="SOME_PLACE_ID_2">
      <img class="place-icon" src="icon_url_2.png" alt="Icon">
      <span class="place-name">Place Name Two</span> -
      <span class="place-vicinity">456 Oak Ave</span>
    </li>
    -->
        <li class="loading-message">Loading places...</li>
    </ul>
</div>

Element wyszukiwania miejsc jest implementowany za pomocą komponentu <gmp-place-search>. Aby skonfigurować typ wyszukiwania, umieść wewnątrz jeden z tych komponentów konfiguracji:

  • <gmp-place-text-search-request> w przypadku wyszukiwania tekstowego.
  • <gmp-place-nearby-search-request> w przypadku wyszukiwania w pobliżu.

Aby określić sposób wyświetlania wyników, możesz użyć skrótu <gmp-place-all-content> lub podać własny zestaw poszczególnych komponentów prezentacji. Kluczowe atrybuty, takie jak selectable (aby umożliwić klikanie elementów listy) i orientation (w przypadku układu poziomego lub pionowego), można ustawić bezpośrednio w komponencie nadrzędnym.

Przykład wyszukiwania w pobliżu
<gmp-place-search orientation="horizontal" selectable>
    <gmp-place-all-content> </gmp-place-all-content>
    <gmp-place-nearby-search-request></gmp-place-nearby-search-request>
</gmp-place-search>
Przykład wyszukiwania tekstowego
<gmp-place-search orientation="horizontal" selectable>
  <gmp-place-all-content> </gmp-place-all-content>
  <gmp-place-text-search-request></gmp-place-text-search-request>
</gmp-place-search>

Dostosowywanie logiki JavaScriptu

W kodzie JavaScriptu uzyskaj odwołanie do komponentu kontrolera wyszukiwania za pomocą document.querySelector(). W zależności od konfiguracji będzie to element <gmp-place-text-search-request> lub <gmp-place-nearby-search-request>.

Następnie ustaw właściwości tego kontrolera, aby zdefiniować wyszukiwanie. Wymagane właściwości zależą od typu wyszukiwania.

W przypadku wyszukiwania tekstowego (<gmp-place-text-search-request>) właściwość podstawowa to textQuery:

const textSearchController = document.querySelector('gmp-place-text-search-request');
textSearchController.textQuery = 'museums in London';

W przypadku wyszukiwania w pobliżu (<gmp-place-nearby-search-request>) musisz zdefiniować obszar wyszukiwania za pomocą parametru locationRestriction. Następnie możesz użyć includedTypes, aby odfiltrować określone rodzaje miejsc na tym obszarze:

const nearbySearchController = document.querySelector('gmp-place-nearby-search-request');
nearbySearchController.locationRestriction = new google.maps.Circle({
    center: { lat: 51.5190, lng: -0.1347 },
    radius: 1000
});
nearbySearchController.includedTypes = ['restaurant'];

Komponent nadrzędny <gmp-place-search> automatycznie inicjuje nowe wyszukiwanie, gdy tylko zostaną ustawione wymagane właściwości jego kontrolera.

  • W przypadku wyszukiwania tekstowego wyszukiwanie jest uruchamiane w momencie przypisania wartości do textQuery.
  • W przypadku wyszukiwania w pobliżu wyszukiwanie jest uruchamiane po podaniu prawidłowego parametru locationRestriction.

Implementowanie elementu Autouzupełnianie miejsc (podstawowe)

Dla deweloperów, którzy potrzebują wyszukiwania bez interfejsu użytkownika elementu wyszukiwania miejsc, dostępny jest element podstawowego autouzupełniania miejsc.

Ten element idealnie nadaje się do tworzenia pola do wprowadzania danych wyszukiwania, zachowując jednocześnie pełną kontrolę nad sposobem wyświetlania wyników w niestandardowym interfejsie użytkownika. Jedynym zadaniem elementu autouzupełniania jest dostarczanie podpowiedzi miejsc podczas wpisywania tekstu przez użytkownika i programowe udostępnianie identyfikatora miejsca dla wybranego miejsca.

Nie wyświetla żadnych szczegółów ani nie udostępnia żadnych innych informacji dostępnych programowo.

Obecne wdrożenie

Dotychczasowa logika prawdopodobnie obejmuje:

  • renderowanie pola do wprowadzania danych na stronie, które wywołuje autouzupełnianie miejsc podczas wpisywania tekstu przez użytkownika i wyświetla wyniki;
  • użycie identyfikatora miejsca wybranego przez użytkownika, aby uzyskać więcej informacji, np. za pomocą interfejsu Place Details API;
  • Wyświetlam szczegóły wybranego miejsca.

Migracja do elementu Autouzupełnianie miejsc

Modyfikowanie struktury HTML

Znajdź i usuń element HTML, do którego dołączony jest widżet autouzupełniania. Prawdopodobnie używa standardowego pola do wprowadzania danych HTML.

<input id="pac-input" type="text" placeholder="Search for a location" />

Przykładowy nowy kod HTML, który używa komponentu internetowego do inicjowania elementu autouzupełniania podstawowych informacji o miejscu na stronie.

<gmp-basic-place-autocomplete></gmp-basic-place-autocomplete>

Dostosowywanie logiki JavaScriptu

Logika JavaScriptu prawdopodobnie obejmuje utworzenie widżetu autouzupełniania dołączonego do elementu HTML input. Ten widżet nasłuchuje zdarzenia place_changed, wywołując działanie ze zwróconymi danymi.

Przykładowy istniejący kod JavaScript do usunięcia:

// Get the input element
const input = document.getElementById("pac-input");

// Create the Autocomplete widget instance
const autocomplete = new google.maps.places.Autocomplete(input, {
  fields: ["place_id", "geometry", "name"]
});

// Add a listener for the 'place_changed' event
autocomplete.addListener("place_changed", () => {
  // Your logic to get and display place information
  console.log(place.place_id);
});

Nowa logika JavaScriptu pobierze odwołanie do elementu podstawowego autouzupełniania miejsc i będzie nasłuchiwać zdarzeń gmp-select:

const placeAutocomplete = document.querySelector('gmp-basic-place-autocomplete');

placeAutocomplete.addEventListener('gmp-select', (event) => {
  console.log(event.place);
});

Po wybraniu miejsca w menu autouzupełniania zostanie wywołane zdarzenie gmp-select. Identyfikator miejsca wybranego miejsca można pobrać z obiektu event. Identyfikator miejsca może być następnie użyty do zainicjowania instancji elementu informacji o miejscu, aby wyświetlić szczegóły wybranego miejsca.

Dostosowywanie uchwytu

Dostosowywanie elementu informacji o miejscu

Orientacja

Element informacji o miejscu może być renderowany zarówno w orientacji poziomej, jak i pionowej. Użyj atrybutu orientation w elemencie gmp-place-details-compact, aby wybrać orientację pionową lub poziomą. Na przykład:

<gmp-place-details-compact orientation="vertical">

Wybierz pola do renderowania

Użyj elementów treści, aby określić treść, która ma być renderowana w elemencie Szczegóły miejsca. Na przykład wykluczenie elementu treści <gmp-place-type> spowodowałoby, że element informacji o miejscu nie będzie renderować typu wybranego miejsca. Pełną listę elementów treści znajdziesz w dokumentacji referencyjnej PlaceContentConfigElement.

Dodanie lub usunięcie pól z elementu informacje o miejscu nie zmienia kosztu renderowania elementu na stronie.

Ustawianie stylów CSS

Dostępne są niestandardowe właściwości CSS, które umożliwiają konfigurowanie kolorów i czcionek elementu. Aby na przykład ustawić zielone tło elementu, ustaw tę właściwość CSS:

gmp-place-details-compact {
  --gmp-mat-color-surface: green;
}

Więcej informacji znajdziesz w dokumentacji referencyjnej PlaceDetailsCompactElement.

Dostosowywanie elementu wyszukiwania miejsc

Orientacja

Element wyszukiwania miejsc może być renderowany zarówno w orientacji poziomej, jak i pionowej. Użyj atrybutu orientation w elemencie <gmp-place-search>, aby wybrać orientację pionową lub poziomą. Na przykład:

<gmp-place-search orientation="horizontal" selectable>

Wybierz pola do renderowania

Użyj elementów treści, aby określić treści, które mają być renderowane w elemencie wyszukiwania miejsc. Element <gmp-place-all-content> może służyć do wyświetlania wszystkich treści, a do skonfigurowania renderowanych treści można użyć wybranych tagów HTML.

Jeśli w elemencie <gmp-place-content-config> umieścisz element <gmp-place-address>, wyświetlany będzie tylko adres każdego miejsca, na przykład:

<gmp-place-search orientation="horizontal" selectable>
  <gmp-place-content-config>
    <gmp-place-address></gmp-place-address>
  </gmp-place-content-config>
  <gmp-place-text-search-request></gmp-place-text-search-request>
</gmp-place-search>

Dostosowywanie podstawowego elementu autouzupełniania miejsc

Ustawianie stylów CSS

Dostępne są niestandardowe właściwości CSS, które umożliwiają dostosowanie wyglądu i działania elementu autouzupełniania. Aby na przykład ustawić kolor tła na jasnofioletowy, ustaw właściwość background-color elementu.

gmp-basic-place-autocomplete {
  background-color: #d993e6;
}

Więcej informacji znajdziesz w dokumentacji referencyjnej BasicPlaceAutocompleteElement.

Obsługa zdarzeń i danych

Elementy Places UI Kit to interaktywne komponenty, które umożliwiają nasłuchiwanie zdarzeń i programowe pobieranie danych.

Nasłuchiwanie zdarzeń

Do elementów możesz dodawać detektory zdarzeń, aby wywoływać działania na podstawie interakcji użytkownika lub stanu elementu.

Zdarzenie wyboru

  • gmp-select: to zdarzenie jest wywoływane, gdy użytkownik dokona wyboru.
    • W przypadku elementu wyszukiwania miejsc jest ono wywoływane, gdy użytkownik kliknie miejsce na liście wyników.
    • W przypadku podstawowego elementu autouzupełniania miejsc jest on aktywowany, gdy użytkownik kliknie podpowiedź na liście.

Zdarzenia typowe

Wszystkie elementy wyszukiwania miejsc, informacji o miejscu i podstawowego autouzupełniania miejsc obsługują te zdarzenia:

  • gmp-load: wywoływane, gdy element i jego zawartość zostaną wczytane i wyrenderowane.
  • gmp-requesterror: wywoływane, gdy żądanie do serwera nie powiedzie się, np. z powodu nieprawidłowego klucza interfejsu API.

Automatyczny dostęp do danych elementów

Możesz automatycznie pobierać określone dane z elementów po ich załadowaniu lub po wejściu z nimi w interakcję.

  • W przypadku elementów wyszukiwania miejsc i informacji o miejscu możesz pobrać te informacje:
    • Identyfikator miejsca
    • Lokalizacja (szerokość i długość geograficzna)
    • Widoczny obszar
  • W przypadku podstawowego elementu autouzupełniania miejsc możesz pobrać te informacje:
    • Identyfikator miejsca

Wszystkie inne dane zawarte w elementach nie są dostępne automatycznie.

Więcej szczegółowych przykładów znajdziesz w dokumentacji elementu wyszukiwania miejsc, elementu informacji o miejscu i podstawowego elementu autouzupełniania miejsc.

Testowanie i ulepszanie

Po zintegrowaniu elementów Places UI Kit kluczowe znaczenie dla płynnego przejścia i pozytywnych wrażeń użytkowników ma przeprowadzenie testów. Testy powinny obejmować kilka kluczowych obszarów i wszystkie wdrożone elementy: informacje o miejscu, wyszukiwanie miejsc i podstawowe autouzupełnianie miejsc.

Element informacji o miejscu

W przypadku elementu Informacje o miejscu zacznij od sprawdzenia, czy szczegóły są wyświetlane prawidłowo dla różnych miejsc. Przetestuj, przekazując różne identyfikatory miejsc do właściwości .place elementu <gmp-place-details-place-request>. Użyj identyfikatorów reprezentujących różne typy placówek (firmy z danymi rozszerzonymi, ciekawe miejsca, podstawowe adresy) i miejsca w różnych regionach lub językach. Zwróć szczególną uwagę na formatowanie, układ i obecność treści.

Element wyszukiwania miejsc

Jeśli masz zaimplementowany element wyszukiwania miejsc, sprawdź, jak jest renderowany i jak działa w różnych scenariuszach wyszukiwania.

  • W przypadku wyszukiwania tekstowego przetestuj ustawienie właściwości textQuery w elemencie <gmp-place-text-search-request> z różnymi danymi wejściowymi: ogólnymi zapytaniami, konkretnymi adresami i zapytaniami z ustawieniami lokalizacji.
  • W przypadku wyszukiwania w pobliżu przetestuj, ustawiając właściwości locationRestriction i includedTypes w elemencie <gmp-place-nearby-search-request>. Używaj różnych rozmiarów lokalizacji i filtrów typów.

Sprawdź, czy lista zawiera odpowiednie wyniki i czy po wybraniu elementu zdarzenie gmp-select jest prawidłowo wywoływane.

Podstawowy element autouzupełniania miejsc

W przypadku elementu Basic Autouzupełnianie miejsc skup się na testowaniu interakcji użytkownika i danych przekazywanych przez zdarzenie wyboru. Sprawdź, czy zdarzenie gmp-select jest niezawodnie wywoływane, gdy użytkownik kliknie podpowiedź. Sprawdź, czy obiekt event.place w module obsługi zdarzeń zawiera prawidłowy identyfikator miejsca.

Co najważniejsze, przetestuj cały proces: wybierz miejsce z menu autouzupełniania i sprawdź, czy jego identyfikator miejsca może zostać użyty do wypełnienia innego elementu, np. elementu z informacjami o miejscu.

Obsługa błędów

Rygorystyczne testowanie obsługi błędów jest niezbędne we wszystkich komponentach. Zasymuluj przekazywanie nieprawidłowych lub nieistniejących identyfikatorów miejsc do elementu Informacje o miejscu lub używanie nieprawidłowych parametrów wyszukiwania w elemencie Wyszukiwanie miejsc. Wywołaj zdarzenie gmp-requesterror, symulując problemy z siecią lub używając nieprawidłowego klucza interfejsu API, aby upewnić się, że aplikacja prawidłowo je obsługuje. Zaimplementuj przyjazne dla użytkownika komunikaty o błędach i rejestrowanie, aby zapobiec uszkodzeniu lub dezorientacji interfejsu.