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

Dowiedz się, jak przeprowadzić migrację z dotychczasowej implementacji interfejsu Places API lub klasy Place Class na komponenty Places UI Kit components.

Komu przyda się ten przewodnik

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

  • wysyłasz żądania HTTP do punktów końcowych interfejsu Places API (nowych lub starszych);
  • używasz klasy Place w Maps JavaScript API;
  • obsługujesz odpowiedź interfejsu API, aby renderować informacje 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 na potrzeby Places UI Kit. Więcej informacji, w tym o ograniczaniu klucza, znajdziesz w artykule Używanie kluczy interfejsu API.

Aktualizowanie wczytywania Maps JavaScript API

Places UI Kit wymaga wczytywania Maps JavaScript API za pomocą metody dynamicznego importowania biblioteki. Jeśli używasz tagu bezpośredniego wczytywania skryptu , musisz go zaktualizować.

Gdy zaktualizujesz skrypt wczytywania Maps JavaScript API, zaimportuj wymagane biblioteki aby używać Places UI Kit.

Implementowanie elementu Informacje o miejscu

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

Obecna implementacja

  • Wywołujesz informacje o miejscu za pomocą żądania HTTP lub używasz klasy Place w JavaScript API.
  • Analizujesz odpowiedź interfejsu API i wyświetlasz informacje o miejscu za pomocą 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 (divy, spany na nazwę, adres, zdjęcia itp.) kodem HTML elementu Informacje o miejscu.

Możesz wybrać jeden z 2 elementów:

  • Element Informacje o miejscu (kompaktowy)
  • Element Informacje o miejscu

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

Twój 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 JavaScript

Dotychczasowa logika

Twoja dotychczasowa logika prawdopodobnie obejmuje:

  • pobieranie identyfikatora miejsca;
  • używanie PlacesService().getDetails() lub wywoływanie usługi internetowej;
  • określanie tablicy pól (w przypadku JavaScript API) lub FieldMask (w przypadku usługi internetowej), aby poprosić o konkretne dane;
  • w przypadku wywołania zwrotnego ręczne wybieranie elementów HTML i wypełnianie ich 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

Twoja nowa logika będzie obejmować:

  • pobieranie identyfikatora miejsca lub obiektu miejsca;
  • pobieranie odwołania do elementu <gmp-place-details-place-request>;
  • przekazywanie identyfikatora miejsca lub obiektu miejsca do właściwości place w elemencie <gmp-place-details-place-request>.

Poniżej przedstawiono przykład implementacji zestawu interfejsu użytkownika Informacje o miejscu w logice JavaScript. Pobierz odwołanie do elementu Informacje o miejscu. Jeśli ten element istnieje, pobierz odwołanie do elementu Żądanie informacji o miejscu i ustaw właściwość place za pomocą identyfikatora miejsca. W przykładowym kodzie HTML powyżej styl elementu Informacje o miejscu jest ustawiony na display: none. Został on zmieniony na 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 Wyszukiwanie miejsc Element to element HTML , który renderuje wyniki wyszukiwania miejsc w postaci listy.

  • Wykonujesz wyszukiwanie tekstowe lub wyszukiwanie w pobliżu za pomocą żądania HTTP albo używasz klasy Place w JavaScript API.
  • Określasz parametry zapytania, ograniczenia lub preferencje lokalizacji, typy i żądane pola za pomocą FieldMask.
  • Analizujesz odpowiedź interfejsu API, iterujesz po tablicy miejsc i ręcznie tworzysz elementy listy HTML.

Modyfikowanie struktury HTML

Zidentyfikuj kontener HTML, w którym renderujesz listę miejsc. Zastąp niestandardowe elementy HTML (divy, spany na nazwę, adres itp.) elementem HTML Wyszukiwanie miejsc.

Twój dotychczasowy kod HTML może wyglądać 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 Wyszukiwanie miejsc jest implementowany za pomocą komponentu <gmp-place-search>. Aby skonfigurować typ wyszukiwania, dodaj do niego 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ć <gmp-place-all-content> skrótu 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 JavaScript

W JavaScript pobierz 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>) główną właściwością jest 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ą locationRestriction. Następnie możesz użyć includedTypes, aby filtrować pod kątem określonych rodzajów miejsc w 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'];

Gdy tylko zostaną ustawione wymagane właściwości kontrolera, komponent nadrzędny <gmp-place-search> automatycznie rozpocznie nowe wyszukiwanie.

  • W przypadku wyszukiwania tekstowego wyszukiwanie rozpoczyna się, gdy tylko przypiszesz wartość do textQuery.
  • W przypadku wyszukiwania w pobliżu wyszukiwanie rozpoczyna się po podaniu prawidłowego locationRestriction.

Implementowanie elementu Podstawowe autouzupełnianie miejsc

Deweloperzy, którzy potrzebują wyszukiwania bez interfejsu elementu Wyszukiwanie miejsc, mogą użyć elementu Podstawowe autouzupełnianie miejsc.

Ten element idealnie nadaje się do tworzenia pola do wprowadzania danych wyszukiwania, przy jednoczesnym zachowaniu pełnej kontroli nad sposobem wyświetlania wyników w niestandardowym interfejsie użytkownika. Jedynym zadaniem elementu autouzupełniania jest podawanie prognoz miejsc podczas wpisywania tekstu przez użytkownika oraz programowe udostępnianie identyfikatora miejsca wybranego miejsca.

Nie wyświetla on żadnych informacji ani nie udostępnia żadnych innych informacji, do których można uzyskać dostęp programowo.

Obecna implementacja

Twoja dotychczasowa logika prawdopodobnie obejmuje:

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

Migracja do elementu Autouzupełnianie miejsc

Modyfikowanie struktury HTML

Zidentyfikuj i usuń element HTML, do którego dołączasz widżet autouzupełniania. Prawdopodobnie używasz standardowego pola do wprowadzania danych HTML.

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

Przykład nowego kodu HTML, który używa komponentu internetowego do zainicjowania na stronie elementu Podstawowe autouzupełnianie miejsc.

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

Dostosowywanie logiki JavaScript

Twoja logika JavaScript prawdopodobnie obejmuje tworzenie widżetu autouzupełniania dołączonego do elementu HTML input. Ten widżet nasłuchuje zdarzenia place_changed, które wywołuje działanie z zwróconymi danymi.

Przykład dotychczasowego kodu 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);
});

Twoja nowa logika JavaScript pobierze odwołanie do elementu Podstawowe autouzupełnianie 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);
});

Gdy użytkownik wybierze miejsce z menu autouzupełniania, zostanie wywołane zdarzenie gmp-select. Identyfikator miejsca wybranego miejsca można pobrać z obiektu event. Identyfikator miejsca można następnie użyć do zainicjowania instancji elementu Informacje o miejscu, aby wyświetlić informacje o wybranym miejscu.

Obsługa personalizacji

Dostosowywanie elementu Informacje o miejscu

Orientacja

Element Informacje o miejscu można renderować w orientacji poziomej i pionowej. Aby wybrać orientację pionową lub poziomą, użyj atrybutu orientation w gmp-place-details-compact. Na przykład:

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

Wybieranie pól do renderowania

Użyj elementów treści, aby określić, jakie treści mają być renderowane w elemencie Informacje o miejscu. Na przykład wykluczenie elementu treści <gmp-place-type> spowoduje, że element Informacje o miejscu przestanie renderować typ miejsca wybranego miejsca. Pełną listę elementów treści znajdziesz w PlaceContentConfigElement dokumentacji.

Dodawanie lub usuwanie 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 PlaceDetailsCompactElement.

Dostosowywanie elementu Wyszukiwanie miejsc

Orientacja

Element Wyszukiwanie miejsc można renderować w orientacji poziomej i pionowej. Aby wybrać orientację pionową lub poziomą, użyj atrybutu orientation w <gmp-place-search>. Na przykład:

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

Wybieranie pól do renderowania

Użyj elementów treści, aby określić, jakie treści mają być renderowane w elemencie Wyszukiwanie miejsc. Element <gmp-place-all-content> może służyć do wyświetlania całej treści lub do konfigurowania renderowanej treści można użyć wyboru tagów HTML.

Dodanie <gmp-place-address> w <gmp-place-content-config> spowoduje, że dla każdego miejsca będzie renderowany tylko adres, np.:

<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 elementu Podstawowe autouzupełnianie miejsc

Ustawianie stylów CSS

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

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

Więcej informacji znajdziesz w dokumentacji 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 Wyszukiwanie miejsc jest wywoływane, gdy użytkownik kliknie miejsce na liście wyników.
    • W przypadku elementu Podstawowe autouzupełnianie miejsc jest wywoływane, gdy użytkownik kliknie prognozę na liście.

Typowe zdarzenia

Elementy Wyszukiwanie miejsc, Informacje o miejscu i Podstawowe autouzupełnianie 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.

Programowe uzyskiwanie dostępu do danych elementu

Po wczytaniu elementów lub wejściu z nimi w interakcję możesz programowo pobierać z nich konkretne dane.

  • W przypadku elementu Wyszukiwanie miejsc i elementu Informacje o miejscu możesz pobrać te informacje:
    • Identyfikator miejsca
    • Lokalizacja (szerokość i długość geograficzna)
    • Widoczny obszar
  • W przypadku elementu Podstawowe autouzupełnianie miejsc możesz pobrać te informacje:
    • Identyfikator miejsca

Do wszystkich innych danych zawartych w elementach nie można uzyskać dostępu programowo.

Bardziej szczegółowe przykłady znajdziesz w dokumentacji elementu Wyszukiwanie miejsc, elementu Informacje o miejscu, i elementu Podstawowe autouzupełnianie miejsc.

Testowanie i dopracowywanie

Po zintegrowaniu elementów Places UI Kit testowanie jest kluczowe, aby zapewnić płynne przejście i pozytywne wrażenia użytkowników. Testowanie powinno obejmować kilka kluczowych obszarów, w tym wszystkie zaimplementowane elementy: Informacje o miejscu, Wyszukiwanie miejsc i Podstawowe autouzupełnianie miejsc.

Element Informacje o miejscu

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

Element Wyszukiwanie miejsc

Jeśli masz zaimplementowany element Wyszukiwanie miejsc, sprawdź jego renderowanie i działanie w różnych scenariuszach wyszukiwania.

  • W przypadku wyszukiwania tekstowego testuj, ustawiając właściwość textQuery elementu <gmp-place-text-search-request> za pomocą różnych danych wejściowych: ogólnych zapytań, konkretnych adresów i zapytań z preferencjami lokalizacji.
  • W przypadku wyszukiwania w pobliżu testuj, ustawiając właściwości locationRestriction i includedTypes elementu <gmp-place-nearby-search-request>. Używaj różnych rozmiarów lokalizacji i filtrów typów.

Sprawdź, czy lista jest wypełniana odpowiednimi wynikami i czy po wybraniu miejsca prawidłowo wywoływane jest zdarzenie gmp-select.

Element Podstawowe autouzupełnianie miejsc

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

Najważniejsze jest przetestowanie całego procesu: wybierz miejsce z menu autouzupełniania i sprawdź, czy jego identyfikator miejsca można użyć do wypełnienia innego elementu, np. elementu Informacje o miejscu.

Obsługa błędów

Rygorystyczne testowanie obsługi błędów jest niezbędne we wszystkich komponentach. Symuluj przekazywanie nieprawidłowych lub nieistniejących identyfikatorów miejsc do elementu Informacje o miejscu albo używanie nieprawidłowych parametrów wyszukiwania w przypadku elementu 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 logowanie, aby zapobiec uszkodzeniu lub dezorientacji interfejsu.