Autouzupełnianie miejsc

Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

Wstęp

Autouzupełnianie to funkcja biblioteki Miejsc w interfejsie Maps JavaScript API. Możesz użyć autouzupełniania, aby zapewnić aplikacjom możliwość wyszukiwania z wyprzedzeniem w polu wyszukiwania w Mapach Google. Usługa autouzupełniania może dopasować pełne słowa i podłańcuchy, rozpoznając nazwy miejsc, adresy i kody Plus Code. Aplikacje mogą więc wysyłać zapytania jako typy użytkowników, aby na bieżąco podawać prognozy miejsc.

Pierwsze kroki

Zanim zaczniesz korzystać z biblioteki Miejsc w interfejsie Maps JavaScript API, najpierw upewnij się, że interfejs Places API jest włączony w Google Cloud Console, w tym samym projekcie skonfigurowanym dla interfejsu Maps JavaScript API.

Aby wyświetlić listę włączonych interfejsów API:

  1. Otwórz Google Cloud Console.
  2. Kliknij przycisk Wybierz projekt, a potem wybierz ten sam projekt, który masz skonfigurowany w interfejsie Maps JavaScript API, i kliknij Otwórz.
  3. Na liście interfejsów API w panelu znajdź Places API.
  4. Jeśli na liście widzisz interfejs API, nie musisz nic więcej robić. Jeśli interfejsu API nie ma na liście, włącz go:
    1. U góry strony wybierz ENABLE API (Włącz interfejs API), aby wyświetlić kartę Biblioteka. Możesz też wybrać Biblioteka z menu po lewej stronie.
    2. Wyszukaj Places API, a następnie wybierz go z listy wyników.
    3. Wybierz WŁĄCZ. Po zakończeniu procesu Places API pojawi się na liście interfejsów API w panelu.

Wczytuję bibliotekę

Usługa Miejsca to samodzielna biblioteka, niezależna od głównego kodu interfejsu API JavaScript Map Google. Aby korzystać z funkcji zawartych w tej bibliotece, musisz najpierw wczytać go za pomocą parametru libraries w adresie URL rozruchu interfejsu API Map Google:

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places&callback=initMap">
</script>

Więcej informacji znajdziesz w artykule Omówienie bibliotek.

Podsumowanie zajęć

Interfejs API udostępnia 2 rodzaje widżetów autouzupełniania, które możesz dodać za pomocą klas Autocomplete i SearchBox. Oprócz tego możesz użyć klasy AutocompleteService, aby automatycznie pobrać wyniki autouzupełniania (zobacz odniesienie do interfejsu API JavaScript JavaScript: klasa autouzupełniania usługi).

Oto podsumowanie dostępnych zajęć:

  • Autocomplete dodaje pole tekstowe do strony internetowej i monitoruje to pole pod kątem znaków. Gdy użytkownik wpisze tekst, autouzupełnianie zwróci podpowiedzi miejsc w postaci listy rozwijanej. Gdy użytkownik wybierze miejsce z listy, informacje o nim zostaną zwrócone do obiektu autouzupełniania i będzie można je pobrać przez aplikację. Szczegółowe informacje znajdziesz poniżej.
    Autouzupełnianie pola tekstowego i lista podpowiedzi miejsc wybranych podczas wpisywania zapytania przez użytkownika.
    Rysunek 1. Autouzupełnianie pola tekstowego i listy wyboru
    Wypełniony formularz adresowy.
    Ilustracja 2. Wypełniony formularz adresu
  • SearchBox dodaje do strony internetowej pole do wprowadzania tekstu w taki sam sposób jak w przypadku tagu Autocomplete. Oto różnice:
    • Główna różnica wynika z wyników wyświetlanych na liście wyboru. SearchBox udostępnia rozszerzoną listę prognoz, która może zawierać miejsca (zgodnie z definicją w interfejsie Places API) oraz sugerowane wyszukiwane hasła. Jeśli na przykład użytkownik wpisze „'pizza” w polu „pizza”, nowojorska lista może zawierać wyrażenie „pizza” w Szczecinie oraz nazwy różnych sklepów z pizzą.
    • SearchBox oferuje mniej opcji niż Autocomplete, aby zawęzić wyszukiwanie. W pierwszym przypadku odchyla się wyszukiwanie na podstawie określonej wartości LatLngBounds. W tym drugim przypadku możesz ograniczyć wyszukiwanie do konkretnego kraju i konkretnych typów miejsc, a także ustawić granice. Więcej informacji znajdziesz poniżej.
    Wypełniony formularz adresowy.
    Ilustracja 3. Wyświetlanie wyników wyszukiwania i umieszczanie ich na pasku wyszukiwania
    Szczegółowe informacje znajdziesz poniżej.
  • Aby automatycznie uzyskiwać prognozy, możesz utworzyć obiekt AutocompleteService. Zadzwoń pod numer getPlacePredictions(), aby pobrać pasujące miejsca, lub getQueryPredictions(), aby pobrać pasujące miejsca i sugerowane wyszukiwane słowa. Uwaga: AutocompleteService nie dodaje żadnych elementów interfejsu. Zamiast tego powyższe metody zwracają tablicę obiektów prognozowania. Każdy obiekt prognozy zawiera tekst prognozy, a także informacje referencyjne i informacje o tym, jak wynik pasuje do danych wejściowych użytkownika. Szczegółowe informacje znajdziesz poniżej.

Dodawanie widżetu autouzupełniania

Widżet Autocomplete tworzy pole do wprowadzania tekstu na stronie internetowej, podaje prognozy miejsc na liście wyboru interfejsu i zwraca szczegóły miejsca w odpowiedzi na żądanie getPlace(). Każdy wpis na liście odpowiada pojedynczemu miejscu (zgodnie z definicją w interfejsie Places API).

konstruktor Autocomplete przyjmuje 2 argumenty:

  • Element HTML input typu text. To jest pole do wprowadzania danych, które będzie używane do autouzupełniania wyników.
  • Opcjonalny argument AutocompleteOptions, który może zawierać te właściwości:
    • Tablica danych fields, która ma zostać uwzględniona w odpowiedzi Place Detailsdla wybranego użytkownika PlaceResult. Jeśli właściwość nie zostanie ustawiona lub zostanie przekazany obiekt ['ALL'], wszystkie dostępne pola zostaną zwrócone i rozliczone w aplikacji (nie jest to zalecane w przypadku wdrożeń produkcyjnych). Listę pól znajdziesz w sekcji PlaceResult.
    • Tablica types, która określa wyraźny typ lub kolekcję typów, zgodnie z obsługiwanymi typami. Jeśli nie określisz typu, zwracane będą wszystkie typy.
    • bounds to obiekt google.maps.LatLngBounds określający obszar wyszukiwania miejsc. Wyniki są stronnicze, ale nie ograniczają się do miejsc w tych granicach.
    • strictBounds to boolean, który określa, czy interfejs API musi zwracać tylko te miejsca w regionie określonym przez bounds. Interfejs API nie zwraca wyników poza ten region, nawet jeśli pasują one do danych wejściowych użytkownika.
    • Za pomocą componentRestrictions można ograniczyć wyniki do konkretnych grup. Obecnie możesz korzystać z componentRestrictions, aby filtrować według maksymalnie 5 krajów. Kraje muszą być przekazywane jako dwuznakowy kod kraju zgodny ze standardem ISO 3166-1 alfa-2. Musisz podać wiele krajów jako listę kodów krajów.

      Uwaga: jeśli z kodem kraju otrzymujesz nieoczekiwane wyniki, sprawdź, czy używasz kodu zawierającego kraje, terytoria zależne lub specjalne obszary zainteresowań, których chcesz używać. Informacje o kodzie znajdziesz na stronie Wikipedia: lista kodów krajów w formacie ISO 3166 lub na platformie przeglądania online online.

    • Za pomocą metody placeIdOnly można przekazać widżetowi Autocomplete pobieranie tylko identyfikatorów miejsc. W przypadku wywołania getPlace() w obiekcie Autocomplete udostępnionym PlaceResult będą ustawione tylko właściwości place id, types i name. Zwróconego identyfikatora możesz użyć w przypadku połączeń z usługami Miejsca, Geokodowanie, Trasa dojazdu lub Odległość.

Ograniczenia podpowiedzi autouzupełniania

Domyślnie autouzupełnianie miejsc prezentuje wszystkie typy miejsc, odchylenia na podstawie prognozy dotyczące lokalizacji użytkownika oraz pobiera wszystkie dostępne pola danych dla wybranego miejsca. Ustaw opcje autouzupełniania miejsc, aby prezentować trafniejsze prognozy na podstawie przypadku użycia.

Ustawianie opcji podczas budowy

Konstruktor Autocomplete akceptuje parametr AutocompleteOptions, aby ustawiać ograniczenia przy tworzeniu widżetu. Poniższy przykład pokazuje, jak ustawić opcje bounds, componentRestrictions i types, aby zażądać miejsc typu establishment, faworyzując te z określonego obszaru geograficznego i ograniczając prognozy tylko do miejsc w Stanach Zjednoczonych. Ustawienie opcji fields określa, jakie informacje o wybranym miejscu użytkownika są zwracane.

Wywołaj setOptions(), aby zmienić wartość opcji istniejącego widżetu.

TypeScript

const center = { lat: 50.064192, lng: -130.605469 };
// Create a bounding box with sides ~10km away from the center point
const defaultBounds = {
  north: center.lat + 0.1,
  south: center.lat - 0.1,
  east: center.lng + 0.1,
  west: center.lng - 0.1,
};
const input = document.getElementById("pac-input") as HTMLInputElement;
const options = {
  bounds: defaultBounds,
  componentRestrictions: { country: "us" },
  fields: ["address_components", "geometry", "icon", "name"],
  strictBounds: false,
  types: ["establishment"],
};

const autocomplete = new google.maps.places.Autocomplete(input, options);

JavaScript

const center = { lat: 50.064192, lng: -130.605469 };
// Create a bounding box with sides ~10km away from the center point
const defaultBounds = {
  north: center.lat + 0.1,
  south: center.lat - 0.1,
  east: center.lng + 0.1,
  west: center.lng - 0.1,
};
const input = document.getElementById("pac-input");
const options = {
  bounds: defaultBounds,
  componentRestrictions: { country: "us" },
  fields: ["address_components", "geometry", "icon", "name"],
  strictBounds: false,
  types: ["establishment"],
};
const autocomplete = new google.maps.places.Autocomplete(input, options);

Określ pola danych

Określ pola danych, aby uniknąć opłat za kody SKU danych miejsc, których nie potrzebujesz. Umieść właściwość fields w obrębie znaczników AutocompleteOptions, które są przekazywane do konstruktora widżetu, jak pokazano w poprzednim przykładzie. Możesz też wywołać właściwość setFields() w istniejącym obiekcie Autocomplete.

autocomplete.setFields(["place_id", "geometry", "name"]);

Zdefiniuj odchylenia i granice obszaru wyszukiwania na potrzeby autouzupełniania

Wyniki autouzupełniania możesz stronnić w przybliżeniu przybliżonej lokalizacji lub obszaru:

  • Ustaw granice tworzenia obiektu Autocomplete.
  • Zmień granice istniejącego obiektu Autocomplete.
  • Ustaw granice na widocznym obszarze mapy.
  • Ogranicz wyszukiwanie do określonych granic.
  • Ogranicz wyszukiwanie do określonego kraju.

Poprzedni przykład pokazuje granice tworzenia przy tworzeniu. Poniższe przykłady pokazują inne techniki odchylenia.

Zmienianie granic istniejącego autouzupełniania

Wywołaj setBounds(), aby zmienić obszar wyszukiwania na istniejącym elemencie Autocomplete w przypadku prostokątnych granic.

TypeScript

const southwest = { lat: 5.6108, lng: 136.589326 };
const northeast = { lat: 61.179287, lng: 2.64325 };
const newBounds = new google.maps.LatLngBounds(southwest, northeast);

autocomplete.setBounds(newBounds);

JavaScript

const southwest = { lat: 5.6108, lng: 136.589326 };
const northeast = { lat: 61.179287, lng: 2.64325 };
const newBounds = new google.maps.LatLngBounds(southwest, northeast);

autocomplete.setBounds(newBounds);
Ustawianie granic na widocznym obszarze mapy

Użyj metody bindTo(), aby odchylić wyniki w widocznym obszarze mapy, nawet gdy widoczny obszar się zmieni.

TypeScript

autocomplete.bindTo("bounds", map);

JavaScript

autocomplete.bindTo("bounds", map);

Użyj tagu unbind(), aby usunąć podpowiedź autouzupełniania z widocznego obszaru na mapie.

TypeScript

autocomplete.unbind("bounds");
autocomplete.setBounds({ east: 180, west: -180, north: 90, south: -90 });

JavaScript

autocomplete.unbind("bounds");
autocomplete.setBounds({ east: 180, west: -180, north: 90, south: -90 });

Zobacz przykład

Ogranicz wyszukiwanie do bieżących granic

Ustaw opcję strictBounds, aby ograniczyć wyniki do bieżących granic, niezależnie od widocznego obszaru mapy lub prostokątnych granic.

autocomplete.setOptions({ strictBounds: true });
Ograniczanie podpowiedzi do określonego kraju

Aby ograniczyć autouzupełnienie wyszukiwania do określonego zestawu maksymalnie 5 krajów, użyj opcji componentRestrictions lub wywołaj metodę setComponentRestrictions().

TypeScript

autocomplete.setComponentRestrictions({
  country: ["us", "pr", "vi", "gu", "mp"],
});

JavaScript

autocomplete.setComponentRestrictions({
  country: ["us", "pr", "vi", "gu", "mp"],
});

Zobacz przykład

Typy miejsc z ograniczeniami

Aby ograniczyć prognozy do określonych typów miejsc, użyj opcji types lub wywołaj setTypes(). To ograniczenie określa typ lub kolekcję typów, jak opisano w sekcji Typy miejsc. Jeśli nie określono żadnego ograniczenia, zwracane są wszystkie typy.

Wartość opcji types lub wartość przekazana do setTypes() możesz określić w ten sposób:

  • Tablica zawierająca do 5 wartości z tabeli 1 lub tabeli 2z typów miejsc. Przykład:

    types: ['hospital', 'pharmacy', 'bakery', 'country']

    lub:

    autocomplete.setTypes(['hospital', 'pharmacy', 'bakery', 'country']);
  • Dowolny filtr w tabeli 3 Typy miejsc. Możesz podać tylko jedną wartość z tabeli 3.

Prośba zostanie odrzucona, jeśli:

  • Możesz określić więcej niż 5 typów.
  • Wskazujesz wszelkie nierozpoznane typy.
  • Mieszaj dowolne typy z tabeli 1 lub tabeli 2 z dowolnym filtrem z tabeli 3.

demonstracja dotycząca różnic w podpowiedziach między różnymi typami miejsc.

Odwiedź wersję demonstracyjną

Uzyskiwanie informacji o miejscu

Gdy użytkownik wybierze miejsce na podstawie podpowiedzi dołączonych do pola autouzupełniania, usługa uruchomi zdarzenie place_changed. Aby uzyskać szczegółowe informacje o miejscu:

  1. Utwórz moduł do obsługi zdarzeń place_changed i wywołaj addListener() w obiekcie Autocomplete, aby go dodać.
  2. Wywołaj Autocomplete.getPlace() w obiekcie Autocomplete, aby pobrać obiekt PlaceResult, którego możesz użyć do uzyskania dodatkowych informacji o wybranym miejscu.

Domyślnie, gdy użytkownik wybierze miejsce, funkcja autouzupełniania zwróci wszystkie dostępne pola danych tego miejsca, co spowoduje obciążenie Cię odpowiednią kwotą. Za pomocą właściwości Autocomplete.setFields() możesz określić, które pola danych miejsc zostaną zwrócone. Dowiedz się więcej o obiekcie PlaceResult, w tym liście pól danych o miejscach, o które możesz poprosić. Aby uniknąć płacenia za dane, które nie są Ci potrzebne, użyj właściwości Autocomplete.setFields() do określenia tylko tych danych, których będziesz używać.

Właściwość name zawiera właściwość description z podpowiedzi autouzupełniania w Miejscach. Więcej informacji o wskaźniku description znajdziesz w dokumentacji dotyczącej miejsc autouzupełniania.

W formularzach adresowych warto podać adres w formacie uporządkowanym. Aby zwrócić adres utworzony dla wybranego miejsca, wywołaj metodę Autocomplete.setFields() i określ pole address_components.

Poniższy przykład pokazuje użycie autouzupełniania do wypełnienia pól w formularzu adresu.

TypeScript

function fillInAddress() {
  // Get the place details from the autocomplete object.
  const place = autocomplete.getPlace();
  let address1 = "";
  let postcode = "";

  // Get each component of the address from the place details,
  // and then fill-in the corresponding field on the form.
  // place.address_components are google.maps.GeocoderAddressComponent objects
  // which are documented at http://goo.gle/3l5i5Mr
  for (const component of place.address_components as google.maps.GeocoderAddressComponent[]) {
    // @ts-ignore remove once typings fixed
    const componentType = component.types[0];

    switch (componentType) {
      case "street_number": {
        address1 = `${component.long_name} ${address1}`;
        break;
      }

      case "route": {
        address1 += component.short_name;
        break;
      }

      case "postal_code": {
        postcode = `${component.long_name}${postcode}`;
        break;
      }

      case "postal_code_suffix": {
        postcode = `${postcode}-${component.long_name}`;
        break;
      }

      case "locality":
        (document.querySelector("#locality") as HTMLInputElement).value =
          component.long_name;
        break;

      case "administrative_area_level_1": {
        (document.querySelector("#state") as HTMLInputElement).value =
          component.short_name;
        break;
      }

      case "country":
        (document.querySelector("#country") as HTMLInputElement).value =
          component.long_name;
        break;
    }
  }

  address1Field.value = address1;
  postalField.value = postcode;

  // After filling the form with address components from the Autocomplete
  // prediction, set cursor focus on the second address line to encourage
  // entry of subpremise information such as apartment, unit, or floor number.
  address2Field.focus();
}

JavaScript

function fillInAddress() {
  // Get the place details from the autocomplete object.
  const place = autocomplete.getPlace();
  let address1 = "";
  let postcode = "";

  // Get each component of the address from the place details,
  // and then fill-in the corresponding field on the form.
  // place.address_components are google.maps.GeocoderAddressComponent objects
  // which are documented at http://goo.gle/3l5i5Mr
  for (const component of place.address_components) {
    // @ts-ignore remove once typings fixed
    const componentType = component.types[0];

    switch (componentType) {
      case "street_number": {
        address1 = `${component.long_name} ${address1}`;
        break;
      }

      case "route": {
        address1 += component.short_name;
        break;
      }

      case "postal_code": {
        postcode = `${component.long_name}${postcode}`;
        break;
      }

      case "postal_code_suffix": {
        postcode = `${postcode}-${component.long_name}`;
        break;
      }
      case "locality":
        document.querySelector("#locality").value = component.long_name;
        break;
      case "administrative_area_level_1": {
        document.querySelector("#state").value = component.short_name;
        break;
      }
      case "country":
        document.querySelector("#country").value = component.long_name;
        break;
    }
  }

  address1Field.value = address1;
  postalField.value = postcode;
  // After filling the form with address components from the Autocomplete
  // prediction, set cursor focus on the second address line to encourage
  // entry of subpremise information such as apartment, unit, or floor number.
  address2Field.focus();
}

window.initAutocomplete = initAutocomplete;

Zobacz przykład

Dostosowywanie tekstu zastępczego

Domyślnie pole tekstowe utworzone przez usługę autouzupełniania zawiera standardowy tekst zastępczy. Aby zmodyfikować tekst, ustaw atrybut placeholder w elemencie input:

<input id="searchTextField" type="text" size="50" placeholder="Anything you want!">

Uwaga: domyślny tekst zastępczy jest przetłumaczony automatycznie. Jeśli określisz własną wartość zastępczą, musisz obsługiwać jej lokalizację w aplikacji. Informacje o tym, jak interfejs API JavaScript Map Google wybiera język, którego chcesz używać, znajdziesz w dokumentacji lokalizacji.

Aby dostosować wygląd widżetu, przeczytaj artykuł Zmienianie stylu autouzupełniania i SearchBox.

SearchBox umożliwia wyszukiwanie geograficzne. Możesz dołączyć SearchBox w polu tekstowym, a w miarę wpisywania tekstu usługa zwróci podpowiedzi w formie listy.

SearchBox udostępnia rozszerzoną listę prognoz, która może obejmować miejsca (zgodnie z definicją w interfejsie Places API) oraz sugerowane hasła. Jeśli na przykład użytkownik wpisze „'pizza” w polu „pizza”, nowojorska lista może zawierać wyrażenie „pizza” w Szczecinie oraz nazwy różnych sklepów z pizzą. Gdy użytkownik wybierze miejsce z listy, informacje o nim zostaną zwrócone do obiektu SearchBox i będzie można je pobrać przez aplikację.

konstruktor SearchBox przyjmuje 2 argumenty:

  • Element HTML input typu text. To jest pole wejściowe, do którego usługa SearchBox będzie monitorować i dołączać wyniki.
  • Argument options, który może zawierać właściwość bounds: bounds to obiekt google.maps.LatLngBounds określający obszar wyszukiwania miejsc. Wyniki są stronnicze, ale nie ograniczają się do miejsc w tych granicach.

Poniższy kod używa parametru granicy w celu dopasowania wyników do miejsc w określonym obszarze geograficznym określonym za pomocą współrzędnych laitude/length.

var defaultBounds = new google.maps.LatLngBounds(
  new google.maps.LatLng(-33.8902, 151.1759),
  new google.maps.LatLng(-33.8474, 151.2631));

var input = document.getElementById('searchTextField');

var searchBox = new google.maps.places.SearchBox(input, {
  bounds: defaultBounds
});

Zmiana obszaru wyszukiwania w SearchBox

Aby zmienić obszar wyszukiwania w obiekcie SearchBox, wywołaj obiekt setBounds() w obiekcie SearchBox i przekaż odpowiedni obiekt LatLngBounds.

Zobacz przykład

Uzyskiwanie informacji o miejscu

Gdy użytkownik wybierze element z podpowiedzi dołączonych do pola wyszukiwania, usługa wywoła zdarzenie places_changed. Możesz wywołać właściwość getPlaces() w obiekcie SearchBox, aby pobrać tablicę zawierającą kilka prognoz, z których każdy jest obiektem PlaceResult.

Więcej informacji o obiekcie PlaceResult znajdziesz w dokumentacji wyników wyszukiwania szczegółów miejsca.

TypeScript

// Listen for the event fired when the user selects a prediction and retrieve
// more details for that place.
searchBox.addListener("places_changed", () => {
  const places = searchBox.getPlaces();

  if (places.length == 0) {
    return;
  }

  // Clear out the old markers.
  markers.forEach((marker) => {
    marker.setMap(null);
  });
  markers = [];

  // For each place, get the icon, name and location.
  const bounds = new google.maps.LatLngBounds();

  places.forEach((place) => {
    if (!place.geometry || !place.geometry.location) {
      console.log("Returned place contains no geometry");
      return;
    }

    const icon = {
      url: place.icon as string,
      size: new google.maps.Size(71, 71),
      origin: new google.maps.Point(0, 0),
      anchor: new google.maps.Point(17, 34),
      scaledSize: new google.maps.Size(25, 25),
    };

    // Create a marker for each place.
    markers.push(
      new google.maps.Marker({
        map,
        icon,
        title: place.name,
        position: place.geometry.location,
      })
    );

    if (place.geometry.viewport) {
      // Only geocodes have viewport.
      bounds.union(place.geometry.viewport);
    } else {
      bounds.extend(place.geometry.location);
    }
  });
  map.fitBounds(bounds);
});

JavaScript

// Listen for the event fired when the user selects a prediction and retrieve
// more details for that place.
searchBox.addListener("places_changed", () => {
  const places = searchBox.getPlaces();

  if (places.length == 0) {
    return;
  }

  // Clear out the old markers.
  markers.forEach((marker) => {
    marker.setMap(null);
  });
  markers = [];

  // For each place, get the icon, name and location.
  const bounds = new google.maps.LatLngBounds();

  places.forEach((place) => {
    if (!place.geometry || !place.geometry.location) {
      console.log("Returned place contains no geometry");
      return;
    }

    const icon = {
      url: place.icon,
      size: new google.maps.Size(71, 71),
      origin: new google.maps.Point(0, 0),
      anchor: new google.maps.Point(17, 34),
      scaledSize: new google.maps.Size(25, 25),
    };

    // Create a marker for each place.
    markers.push(
      new google.maps.Marker({
        map,
        icon,
        title: place.name,
        position: place.geometry.location,
      })
    );
    if (place.geometry.viewport) {
      // Only geocodes have viewport.
      bounds.union(place.geometry.viewport);
    } else {
      bounds.extend(place.geometry.location);
    }
  });
  map.fitBounds(bounds);
});

Zobacz przykład

Aby dostosować wygląd widżetu, przeczytaj artykuł Zmienianie stylu autouzupełniania i SearchBox.

Automatyczne pobieranie prognoz dotyczących autouzupełniania miejsc

Aby pobrać prognozy automatycznie, użyj klasy AutocompleteService. AutocompleteService nie dodaje żadnych elementów interfejsu. Zamiast tego zwraca tablicę obiektów prognozowania, które zawierają tekst prognozy, informacje referencyjne i informacje o tym, jak wynik pasuje do danych wejściowych użytkownika. Jest to przydatne, jeśli chcesz mieć większą kontrolę nad interfejsem użytkownika niż ta, którą zapewniają Autocomplete i SearchBox opisane powyżej.

AutocompleteService udostępnia te metody:

  • getPlacePredictions() zwraca podpowiedzi dotyczące miejsc. Uwaga: miejsce to miejsce, lokalizacja geograficzna lub ważne miejsce zdefiniowane przez interfejs Places API.
  • getQueryPredictions() zwraca rozszerzoną listę prognoz, która może zawierać miejsca (zgodnie z definicją w interfejsie Places API) oraz sugerowane hasła. Jeśli na przykład użytkownik wpisze „'pizza” w polu „pizza”, nowojorska lista może zawierać wyrażenie „pizza” w Szczecinie oraz nazwy różnych sklepów z pizzą.

Obie powyższe metody zwracają tablicę obiektów prognoz w następującej formie:

  • description to dopasowana prognoza.
  • distance_meters to odległość miejsca od podanych AutocompletionRequest.origin.
  • Ciąg matched_substrings zawiera w opisie podłańcuch, który pasuje do elementów w danych wejściowych użytkownika. Jest to przydatne, aby wyróżnić te podłańcuchy w aplikacji. W wielu przypadkach zapytanie pojawi się jako podłańcuch pola opisu.
    • length to długość podłańcucha.
    • offset to przesunięcie znaków mierzone od początku ciągu tekstowego, w którym pojawia się pasujący podłańcuch.
  • place_id to identyfikator tekstowy, który jednoznacznie identyfikuje miejsce. Aby pobrać informacje o miejscu, przekaż ten identyfikator w polu placeId w żądaniu Szczegóły miejsca. Dowiedz się więcej o wskazaniu miejsca za pomocą identyfikatora miejsca.
  • terms to tablica zawierająca elementy zapytania. W przypadku danego miejsca każdy element zazwyczaj stanowi część adresu.
    • offset to przesunięcie znaków mierzone od początku ciągu tekstowego, w którym pojawia się pasujący podłańcuch.
    • value to pasujące hasło.

Poniższy przykład pokazuje żądanie prognozy zapytania dla wyrażenia 'pizza Near' powoduje wyświetlenie wyniku na liście.

TypeScript

// This example retrieves autocomplete predictions programmatically from the
// autocomplete service, and displays them as an HTML list.
// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">
function initService(): void {
  const displaySuggestions = function (
    predictions: google.maps.places.QueryAutocompletePrediction[] | null,
    status: google.maps.places.PlacesServiceStatus
  ) {
    if (status != google.maps.places.PlacesServiceStatus.OK || !predictions) {
      alert(status);
      return;
    }

    predictions.forEach((prediction) => {
      const li = document.createElement("li");

      li.appendChild(document.createTextNode(prediction.description));
      (document.getElementById("results") as HTMLUListElement).appendChild(li);
    });
  };

  const service = new google.maps.places.AutocompleteService();

  service.getQueryPredictions({ input: "pizza near Syd" }, displaySuggestions);
}

declare global {
  interface Window {
    initService: () => void;
  }
}
window.initService = initService;

JavaScript

// This example retrieves autocomplete predictions programmatically from the
// autocomplete service, and displays them as an HTML list.
// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">
function initService() {
  const displaySuggestions = function (predictions, status) {
    if (status != google.maps.places.PlacesServiceStatus.OK || !predictions) {
      alert(status);
      return;
    }

    predictions.forEach((prediction) => {
      const li = document.createElement("li");

      li.appendChild(document.createTextNode(prediction.description));
      document.getElementById("results").appendChild(li);
    });
  };

  const service = new google.maps.places.AutocompleteService();

  service.getQueryPredictions({ input: "pizza near Syd" }, displaySuggestions);
}

window.initService = initService;

CSS

HTML

<html>
  <head>
    <title>Retrieving Autocomplete Predictions</title>
    <script src="https://polyfill.io/v3/polyfill.min.js?features=default"></script>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <p>Query suggestions for 'pizza near Syd':</p>
    <ul id="results"></ul>
    <!-- Replace Powered By Google image src with self hosted image. https://developers.google.com/maps/documentation/places/web-service/policies#other_attribution_requirements -->
    <img
      class="powered-by-google"
      src="https://storage.googleapis.com/geo-devrel-public-buckets/powered_by_google_on_white.png"
      alt="Powered by Google"
    />

    <!-- 
     The `defer` attribute causes the callback to execute after the full HTML
     document has been parsed. For non-blocking uses, avoiding race conditions,
     and consistent behavior across browsers, consider loading using Promises
     with https://www.npmjs.com/package/@googlemaps/js-api-loader.
    -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initService&libraries=places&v=weekly"
      defer
    ></script>
  </body>
</html>

Fragment

Zobacz przykład

Tokeny sesji

AutocompleteService.getPlacePredictions() używa tokenów sesji do grupowania żądań autouzupełniania dla celów rozliczeniowych. Tokeny sesji grupują fazę zapytania i wyboru podczas autouzupełniania wyszukiwania w osobnej sesji w celach rozliczeniowych. Sesja rozpoczyna się, gdy użytkownik zacznie wpisywać zapytanie, a kończy, gdy wybierzesz miejsce. Każda sesja może mieć wiele zapytań, po których następuje jedno wybranie miejsca. Po zakończeniu sesji token się wygasł. Aplikacja musi wygenerować nowy token dla każdej sesji. Zalecamy używanie tokenów sesji dla wszystkich sesji autouzupełniania. Jeśli parametr sessionToken jest nieprawidłowy lub ponownie użyjesz tokena sesji, opłata za sesję zostanie naliczona tak, jakby nie podano tokena sesji (każde żądanie jest rozliczane oddzielnie).

Możesz użyć tego samego tokena sesji, aby utworzyć jedno żądanie szczegółów miejsca w miejscu, które wynika z połączenia z: AutocompleteService.getPlacePredictions(). W takim przypadku żądanie autouzupełniania jest łączone z prośbą o podanie informacji o miejscu, a połączenie jest rozliczane jak standardowe żądanie dotyczące szczegółów miejsca. Żądanie autouzupełniania nie jest płatne.

Pamiętaj, aby przekazać unikalny token sesji dla każdej nowej sesji. Jeśli użyjesz tego samego tokena w przypadku więcej niż jednej sesji autouzupełniania, spowoduje to unieważnienie tych sesji autouzupełniania, a każde żądanie autouzupełniania w nieprawidłowych sesjach będzie rozliczane pojedynczo za pomocą kodu SKU na żądanie. Dowiedz się więcej o tokenach sesji

Poniższy przykład pokazuje, jak utworzyć token sesji, a następnie przekazać go w AutocompleteService (funkcja displaySuggestions() została pominięta dla zwięzłości):

// Create a new session token.
var sessionToken = new google.maps.places.AutocompleteSessionToken();

// Pass the token to the autocomplete service.
var autocompleteService = new google.maps.places.AutocompleteService();
autocompleteService.getPlacePredictions({
  input: 'pizza near Syd',
  sessionToken: sessionToken
},
displaySuggestions);

Pamiętaj, aby przekazać unikalny token sesji dla każdej nowej sesji. Jeśli ten sam token zostanie użyty w więcej niż jednej sesji, poszczególne żądania będą rozliczane pojedynczo.

Dowiedz się więcej o tokenach sesji

Wybieranie stylu widżetów autouzupełniania i SearchBox

Domyślnie elementy interfejsu dostarczane przez Autocomplete i SearchBox są uwzględniane w mapie Google. Możesz dostosować style do własnej witryny. Dostępne są te klasy CSS. Wszystkie wymienione poniżej klasy odnoszą się zarówno do widżetów Autocomplete, jak i SearchBox.

Grafika przedstawiająca klasy CSS widżetów autouzupełniania i SearchBox
Klasy CSS dla widżetów autouzupełniania i SearchBox
Klasa CSS Opis
pac-container Element wizualny zawierający listę prognoz zwróconych przez usługę autouzupełniania miejsc. Pojawi się lista pod widżetem Autocomplete lub SearchBox.
pac-icon Ikona widoczna po lewej stronie każdego elementu na liście prognoz.
pac-item Element na liście podpowiedzi dostarczonych przez widżet Autocomplete lub SearchBox.
pac-item:hover Element wyświetlany po najechaniu przez użytkownika kursorem myszy.
pac-item-selected Element wybierany przez użytkownika za pomocą klawiatury. Uwaga: wybrane elementy będą należeć do tej klasy i do klasy pac-item.
pac-item-query Rozpiętość wewnątrz pac-item, która jest główną częścią prognozy. W przypadku lokalizacji geograficznych zawiera ona nazwę miejsca, np. 'Sydney, lub nazwę ulicy i numer, np. '10 King Street'. W przypadku wyszukiwań tekstowych, takich jak 'pizza w Krakowie, zawiera on pełny tekst zapytania. Domyślnie pac-item-query jest czarny. Jeśli element pac-item zawiera dodatkowy tekst, jest on spoza elementu pac-item-query i dziedziczy jego styl z elementu pac-item. Domyślnie jest on szary. Dodatkowy tekst jest zwykle adresem.
pac-matched Część zwróconej podpowiedzi, która pasuje do danych wejściowych użytkownika. Domyślnie pasujący tekst jest pogrubiony. Dopasowany tekst może znajdować się w dowolnym miejscu w obrębie pac-item. Nie musi to być część elementu pac-item-query i może być częściowo w obrębie pac-item-query, a częściowo w tekście pac-item.

Optymalizacja autouzupełniania miejsc

Ta sekcja zawiera sprawdzone metody, które pomogą Ci jak najlepiej wykorzystać możliwości autouzupełniania miejsc.

Oto kilka ogólnych wskazówek:

Sprawdzone metody optymalizacji kosztów

Podstawowa optymalizacja kosztów

Aby zoptymalizować koszt korzystania z usługi autouzupełniania miejsc, użyj masek pól w informacjach o miejscu i autouzupełnianiu miejsc, aby zwracać tylko potrzebne pola danych miejsc.

Zaawansowana optymalizacja kosztów

Rozważ zautomatyzowaną implementację autouzupełniania miejsc, aby uzyskać dostęp do cen za żądanie i poprosić o wyniki interfejsu Geocoding API dotyczące wybranego miejsca zamiast szczegółów miejsca. Cennik za żądanie w połączeniu z interfejsem Geocoding API jest bardziej opłacalny niż w przypadku sesji (na podstawie sesji) w przypadku, gdy spełnione są oba te warunki:

  • Jeśli potrzebujesz tylko szerokości i długości geograficznej lub adresu wybranego miejsca użytkownika, interfejs Geocoding API udostępnia te informacje w przypadku mniejszej liczby wywołań miejsca.
  • Jeśli użytkownicy wybiorą podpowiedź autouzupełniania, która nie przekracza średnio 4 żądań podpowiedzi autouzupełniania, model cenowy według żądania może być bardziej opłacalny niż określanie stawek na sesję.
Aby uzyskać pomoc przy wyborze implementacji autouzupełniania, która odpowiada Twoim potrzebom, kliknij kartę odpowiadającą odpowiedzi na poniższe pytanie.

Czy zgłoszenie wymaga podania informacji innych niż adres i szerokość lub szerokość geograficzna wybranej prognozy?

Tak, chcę dowiedzieć się więcej

Korzystaj z autouzupełniania miejsc opartych na sesjach ze szczegółami miejsca.
Twoje zgłoszenie wymaga szczegółów dotyczących miejsca, takich jak nazwa miejsca, stan firmy lub godziny otwarcia, dlatego implementacja autouzupełniania miejsc powinna używać tokena sesji (automatycznego lub wbudowanego w widżety JavaScript, Androida lub iOS) o łącznej cenie 0,017 USD za sesję i odpowiednich kodów SKU miejsc1..

Implementacja widżetów
Zarządzanie sesjami jest wbudowane w widżety
JavaScript, Androida lub iOS. Obejmuje to prośby o autouzupełnianie miejsc i żądania szczegółów miejsca dotyczące wybranej prognozy. Pamiętaj, aby określić parametr fields, aby mieć pewność, że wysyłasz tylko wymagane pola danych miejsca.

Automatyzacja implementacji
Użyj tokena sesji w żądaniach autouzupełniania miejsc. Podczas wysyłania prośby o szczegóły miejsca związane z wybraną prognozą podaj te parametry:

  1. Identyfikator miejsca podany w odpowiedzi miejsca autouzupełniania.
  2. Token sesji używany w żądaniu autouzupełniania miejsc
  3. Parametr fields określający pola danych miejsca, których potrzebujesz.

Nie, wystarczy tylko adres i lokalizacja

Interfejs Geocoding API może być bardziej ekonomicznym rozwiązaniem niż szczegółowe informacje o miejscu w aplikacji, w zależności od wydajności korzystania z autouzupełniania miejsc. Skuteczność autouzupełniania w każdej aplikacji zależy od danych wprowadzanych przez użytkowników, miejsc, w których jest używana, oraz od tego, czy zostały zastosowane sprawdzone metody optymalizacji skuteczności.

Aby odpowiedzieć na to pytanie, sprawdź, ile znaków średnio wpisuje użytkownik przed wybraniem podpowiedzi autouzupełniania miejsc w Twojej aplikacji.

Czy użytkownicy wybierają średnio podpowiedzi autouzupełniania miejsc w maksymalnie 4 prośbach?

Tak

Zaimplementuj autouzupełnianie miejsc automatycznie bez tokenów sesji i wywołaj interfejs Geocoding API przy użyciu wybranej prognozy miejsca.
Interfejs Geocoding API dostarcza adresy i współrzędne geograficzne w cenie 0,005 USD na żądanie. Dodanie 4 żądań autouzupełniania miejsc – na żądanie kosztuje 0,01132 USD, więc łączny koszt 4 żądań i wywołanie Geocoding API na temat wybranej prognozy miejsca to 0,01632 USD, czyli mniej niż cena autouzupełniania na sesję 0,017 USD1.

Możesz skorzystać ze sprawdzonych metod dotyczących skuteczności, aby ułatwić użytkownikom uzyskanie podpowiedzi, których oczekiwali jeszcze mniej.

Nie

Korzystaj z autouzupełniania miejsc opartych na sesjach ze szczegółami miejsca.
Średnia liczba żądań, które ma zostać wysłana, zanim użytkownik wybierze przewidywaną liczbę wyświetleń z autouzupełniania miejsc przekracza koszt modelu, więc Twoja implementacja autouzupełniania miejsc powinna używać tokena sesji zarówno dla żądań autouzupełniania miejsc, jak i powiązanych z nimi żądań Szczegóły.1

Implementacja widżetów
Zarządzanie sesjami jest wbudowane w widżety JavaScript, Androida lub iOS. Obejmuje to prośby o autouzupełnianie miejsc i żądania szczegółów miejsca dotyczące wybranej prognozy. Pamiętaj, aby podać parametr fields, aby mieć pewność, że wysyłasz tylko żądania dotyczące danych podstawowych.

Automatyzacja implementacji
Użyj tokena sesji w żądaniach autouzupełniania miejsc. Podczas wysyłania prośby o szczegóły miejsca związane z wybraną prognozą podaj te parametry:

  1. Identyfikator miejsca podany w odpowiedzi miejsca autouzupełniania.
  2. Token sesji używany w żądaniu autouzupełniania miejsc
  3. Parametr fields określający pola Dane podstawowe, takie jak adres i geometria.

Rozważ opóźnianie żądań autouzupełniania miejsc
Możesz stosować strategie takie jak opóźnianie żądania autouzupełniania miejsc, dopóki użytkownik nie wpisze pierwszych 3–4 znaków. Dzięki temu liczba żądań w aplikacji będzie mniejsza. Jeśli na przykład wyślesz żądanie autouzupełniania miejsc dla każdego znaku po wpisaniu trzeciego znaku, to gdy użytkownik wpisze 7 znaków, a później wybierze podpowiedź, dla której wyślesz jedno żądanie interfejsu Geocoding API, łączny koszt wyniesie 0,01632 zł (4 * 0,00283 zł do autouzupełniania na żądanie + 0,005 zł do geokodowania).1

Jeśli opóźnione żądania mogą sprawić, że Twoja średnia prośba o wykorzystanie automatyzacji będzie niższa niż 4, postępuj zgodnie ze wskazówkami dotyczącymi implementacji automatycznego uzupełniania miejsca za pomocą interfejsu Geocoding API. Pamiętaj, że opóźnienia żądania mogą być postrzegane przez użytkowników jako takich, którzy mogą spodziewać się podpowiedzi po każdym nowym naciśnięciu klawisza.

Rozważ zastosowanie sprawdzonych metod dotyczących skuteczności, aby ułatwić użytkownikom uzyskiwanie prognoz dotyczących mniejszej liczby znaków.


  1. Wymienione koszty są podane w dolarach amerykańskich. Pełne informacje o cenach znajdziesz na stronie Rozliczenia w Google Maps Platform.

Sprawdzone metody zwiększania skuteczności

Te wskazówki opisują sposoby optymalizacji skuteczności autouzupełniania miejsc:

  • Dodaj ograniczenia językowe, promowanie lokalizacji i preferencja języka (w przypadku implementacji automatycznych) do implementacji autouzupełniania miejsc. Preferencje językowe nie są potrzebne w przypadku widżetów, ponieważ są one wybierane przez przeglądarkę lub urządzenie mobilne użytkownika.
  • Jeśli wraz z mapą pojawia się autouzupełnianie miejsca, możesz wskazać lokalizację na podstawie widocznego obszaru mapy.
  • Jeśli użytkownik nie wybierze jednej z podpowiedzi autouzupełniania (zwykle nie jest to pożądany adres wyniku), możesz spróbować jeszcze raz użyć oryginalnych danych wejściowych użytkownika, aby uzyskać trafniejsze wyniki:
    • Jeśli oczekujesz, że użytkownik poda tylko informacje adresowe, użyj wywołania pierwotnego interfejsu Geocoding API jeszcze raz.
    • Jeśli spodziewasz się, że użytkownik wpisze zapytanie dotyczące określonego miejsca według nazwy lub adresu, użyj żądania Znajdź miejsce. Jeśli wyniki są oczekiwane tylko w określonym regionie, użyj promowania lokalizacji.
    Inne scenariusze, w których najlepiej wykorzystać interfejs Geocoding API, to:
    • Użytkownicy podający adresy podrzędne w krajach innych niż Australia, Nowa Zelandia lub Kanada Na przykład amerykański adres &123 Bowdoin St. 456, Boston MA, USA&quot nie jest obsługiwany przez autouzupełnianie. (Autouzupełnianie obsługuje adresy podrzędne tylko w Australii, Nowej Zelandii i Kanadzie). Obsługiwane formaty adresów w tych 3 krajach to między innymi: " 9/321 Pitt Street, Sydney, New South Wales, Australia" "14/19 Langana Avenue, Browns Bay, Auckland, New Zealand" i "145-112 Renfrew Dr, Markham, Ontario, Canada".
    • Użytkownicy wprowadzający adresy z prefiksami segmentów drogi, np. „"23-30 29th St, Queens&quot” w Nowym Jorku lub „47-380 Kamehameha Hwy, Kaneohe&i” na wyspie Kauai na Hawai.

Limity i zasady użytkowania

Limity

Informacje o limitach i cenach znajdziesz w dokumentacji dotyczącej korzystania z interfejsu Places API i korzystania z nich.

Zasady

Korzystanie z Biblioteki miejsc i interfejsu Maps JavaScript API musi być zgodne z zasadami opisanymi w interfejsie Places API.

Z Warunków korzystania z usługi

Wyświetlaj wymagane
logo i atrybucje

Szanuj prawa autorskie i prawa autorskie. Jeśli korzystasz z danych bez mapy, upewnij się, że logo i informacje o prawach autorskich są widoczne, a logo wyświetla się w technologii Google.

Więcej informacji