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

Cel: zastąpienie implementacji interfejsu Places API lub klasy Place zestawem interfejsu Places UI.

Komu przyda się ten przewodnik

Deweloperzy, którzy:

  • Wysyłanie żądań HTTP do punktów końcowych interfejsu Places API (nowego lub starszego).
  • Używam klasy Place w interfejsie Maps JavaScript API.
  • Obsługa 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 Dynamic Library Import wczytywania interfejsu Maps JavaScript API. Jeśli używasz tagu wczytywania skryptu bezpośredniego, musisz go zaktualizować.

Po zaktualizowaniu skryptu wczytywania interfejsu Maps JavaScript API zaimportuj wymagane biblioteki, aby używać interfejsu Places UI Kit.

Implementowanie elementu Informacje o miejscu

Element Szczegóły miejsca i Element Szczegóły miejsca w wersji kompaktowej to elementy HTML, które wyświetlają szczegółowe informacje o miejscu.

Obecna implementacja

  • Wywołujesz szczegóły miejsca za pomocą żądania HTTP lub klasy miejsca w interfejsie JavaScript API.
  • Analizujesz odpowiedź interfejsu API i wyświetlasz szczegóły miejsca za pomocą HTML i CSS.

Migracja do elementu Informacje o miejscu

Modyfikowanie struktury HTML

Wskaż kontener HTML, w którym są renderowane szczegóły miejsca. Zastąp niestandardowe elementy HTML (divy, spany dla nazwy, adresu, zdjęć itp.) elementem szczegółów miejsca w HTML.

Możesz wybrać 2 elementy:

  • Kompaktowy element Informacje o miejscu
  • Element Informacje o miejscu

Więcej informacji o tym, którego elementu użyć, znajdziesz w sekcji Element Place Details.

Obecny 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

Obecna logika

Istniejąca logika prawdopodobnie obejmuje:

  • Pobieranie identyfikatora miejsca.
  • za pomocą PlacesService().getDetails() lub połączenia z usługą internetową.
  • Określanie tablicy pól (w przypadku interfejsu JS API) lub FieldMask (w przypadku usługi internetowej) w celu zażądania konkretnych danych.
  • W rozwiązaniu wywołania zwrotnego ręcznie wybierasz elementy HTML i wypełniasz je otrzymanymi danymi.

Oto przykład implementacji szczegółów miejsca:

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 place w elemencie <gmp-place-details-place-request>.

Poniżej znajdziesz przykład implementacji interfejsu Place Details UI Kit w logice JavaScript. Uzyskaj odwołanie do elementu szczegółów miejsca. Jeśli ten element istnieje, uzyskaj odniesienie do elementu Place Details Place Request i ustaw właściwość place za pomocą identyfikatora miejsca. W przykładowym kodzie HTML powyżej styl elementu szczegółów miejsca jest ustawiony na display: none. Zaktualizowano go 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 miejsca to element HTML, który wyświetla wyniki wyszukiwania miejsca w postaci listy.

  • Wyszukiwanie tekstowe lub wyszukiwanie w pobliżu możesz przeprowadzić za pomocą żądania HTTP lub klasy Place interfejsu JavaScript API.
  • Parametry zapytania, ograniczenia lub odchylenia lokalizacji, typy i żądane pola określa się za pomocą FieldMask.
  • Analizujesz odpowiedź interfejsu API, iterujesz po tablicy miejsc i ręcznie tworzysz elementy listy HTML.

Modyfikowanie struktury HTML

Określ kontener HTML, w którym renderujesz listę miejsc. Zastąp niestandardowe elementy HTML (divy, spany 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 Wyszukiwanie miejsc jest implementowany za pomocą komponentu <gmp-place-search>. Aby skonfigurować typ wyszukiwania, umieść w nim jeden z tych komponentów konfiguracji:

  • <gmp-place-text-search-request>, aby wyszukać tekst.
  • <gmp-place-nearby-search-request>, aby wyszukać 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 zezwolić na kliknięcia 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 JavaScript uzyskaj odwołanie do komponentu kontrolera wyszukiwania za pomocą kodu 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>) podstawową 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 określić 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'];

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

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

Implementowanie podstawowego elementu autouzupełniania miejsca

Dla programistów, którzy potrzebują wyszukiwania bez interfejsu elementu Place Search Element, dostępny jest podstawowy element Place Autocomplete.

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

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

Obecna implementacja

Istniejąca logika prawdopodobnie obejmuje:

  • Wyświetlanie na stronie pola do wpisywania tekstu, które podczas pisania przez użytkownika wywołuje autouzupełnianie miejsc i wyświetla wyniki.
  • Użyj identyfikatora miejsca wybranego przez użytkownika, aby pobrać więcej szczegółów, np. za pomocą interfejsu Place Details API.
  • Wyświetlanie szczegółów wybranego miejsca.

Migracja do elementu Autouzupełnianie miejsc

Modyfikowanie struktury HTML

Znajdź i usuń element HTML, do którego dołączasz widżet autouzupełniania. Prawdopodobnie używa standardowego pola wejściowego HTML.

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

Przykład nowego kodu HTML, który wykorzystuje komponent internetowy do zainicjowania na stronie elementu podstawowego autouzupełniania miejsca.

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

Dostosowywanie logiki JavaScriptu

Logika JavaScript prawdopodobnie obejmuje utworzenie widżetu Autocomplete dołączonego do elementu HTML input. Widżet nasłuchuje zdarzenia place_changed i wywołuje działanie z zwróconymi danymi.

Przykładowy 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 otrzyma odwołanie do elementu Basic Place Autocomplete 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żna następnie wykorzystać do zainicjowania instancji elementu szczegółów miejsca, aby wyświetlić szczegóły wybranego miejsca.

Dostosowywanie uchwytu

Dostosowywanie elementu Informacje o miejscu

Orientacja

Element szczegółów miejsca może być renderowany w orientacji poziomej i pionowej. Użyj atrybutu orientation w tagu 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ółów miejsca. Na przykład wykluczenie elementu treści <gmp-place-type> spowoduje, że element szczegółów miejsca nie będzie renderować typu wybranego miejsca. Pełną listę elementów treści znajdziesz w PlaceContentConfigElementdokumentacji referencyjnej.

Dodanie lub usunięcie pól z elementu Szczegóły miejsca 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 dotyczącej PlaceDetailsCompactElement.

Dostosowywanie elementu Wyszukiwanie miejsc

Orientacja

Element wyszukiwania miejsca może być renderowany w orientacji poziomej i pionowej. Użyj atrybutu orientation w tagu <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ść, która ma być renderowana w elemencie wyszukiwania miejsca. Element <gmp-place-all-content> może służyć do wyświetlania całej zawartości. Możesz też użyć wyboru tagów HTML, aby skonfigurować renderowaną zawartość.

Umieszczenie <gmp-place-address> w <gmp-place-content-config> spowoduje wyświetlenie tylko adresu każdego miejsca, 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>

Podstawowe dostosowywanie elementu autouzupełniania miejsc

Ustawianie stylów CSS

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

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

Więcej informacji znajdziesz w dokumentacji referencyjnej elementu BasicPlaceAutocompleteElement.

Obsługa zdarzeń i danych

Elementy zestawu interfejsu użytkownika Miejsc to interaktywne komponenty, które umożliwiają nasłuchiwanie zdarzeń i programowe pobieranie danych.

Nasłuchiwanie zdarzeń

Możesz dodawać do elementów 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 miejsca jest wywoływane, gdy użytkownik kliknie miejsce na liście wyników.
    • W przypadku podstawowego elementu autouzupełniania miejsca jest wywoływane, gdy użytkownik kliknie prognozę na liście rozwijanej.

Typowe zdarzenia

Elementy wyszukiwania miejsc, szczegółów miejsca 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.

Automatyczne uzyskiwanie dostępu do danych elementu

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

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

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

Bardziej szczegółowe przykłady znajdziesz w dokumentacji poszczególnych elementów: Element wyszukiwania miejsca, Element szczegółów miejsca i Element podstawowego autouzupełniania miejsca.

Testowanie i doprecyzowywanie

Po zintegrowaniu elementów interfejsu Places UI Kit testowanie jest kluczowe dla płynnego przejścia i pozytywnych wrażeń użytkowników. Testy powinny obejmować kilka kluczowych obszarów i uwzględniać wszystkie wdrożone elementy: szczegóły miejsca, wyszukiwanie miejsc i podstawowe autouzupełnianie miejsc.

Element szczegółów miejsca

W przypadku elementu Szczegóły miejsca zacznij od sprawdzenia, czy szczegóły są wyświetlane prawidłowo w przypadku różnych miejsc. Testuj, przekazując różne identyfikatory miejsca do właściwości .place elementu <gmp-place-details-place-request>. Używaj identyfikatorów reprezentujących różne typy obiektów (firmy z bogatymi danymi, punkty orientacyjne, 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 miejsca

Jeśli masz wdrożony element wyszukiwania miejsca, sprawdź jego renderowanie i działanie 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 uwzględnieniem lokalizacji.
  • W przypadku wyszukiwania w pobliżu przetestuj ustawienie 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 zdarzenia gmp-select jest ono prawidłowo wywoływane.

Podstawowy element autouzupełniania miejsc

W przypadku podstawowego elementu autouzupełniania miejsca 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 prognozę. Sprawdź, czy event.placeobiekt w obsłudze 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że być użyty do wypełnienia innego elementu, np. elementu szczegółów miejsca.

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 szczegółów miejsca albo używanie nieprawidłowych parametrów wyszukiwania w elemencie wyszukiwania miejsc. Wywołaj zdarzenie gmp-requesterror, symulując problemy z siecią lub używając nieprawidłowego klucza API, aby sprawdzić, czy aplikacja prawidłowo sobie z nim radzi. Wdrażaj przyjazne dla użytkownika komunikaty o błędach i logowanie, aby zapobiec uszkodzeniu lub wprowadzeniu w błąd interfejsu.