Autouzupełnianie miejsc (starsza wersja)

Wprowadzenie

Autouzupełnianie to funkcja biblioteki Miejsc w interfejsie Maps JavaScript API. Dzięki autouzupełnianiu możesz zapewnić w swoich aplikacjach działanie pola wyszukiwania Map Google z podpowiedziami podczas wpisywania. Usługa autouzupełniania może dopasowywać pełne słowa i podłańcuchy, rozpoznając nazwy miejsc, adresy i plus codes. Dzięki temu aplikacje mogą wysyłać zapytania, gdy użytkownik wpisuje tekst, aby na bieżąco wyświetlać podpowiedzi dotyczące miejsc. Zgodnie z definicją w Places API „miejsce” może być placówką, położeniem geograficznym lub ważnym punktem orientacyjnym.

Pierwsze kroki

Zanim użyjesz biblioteki Miejsc w Maps JavaScript API, sprawdź, czy interfejs Places API jest włączony w konsoli Google Cloud w tym samym projekcie, który został skonfigurowany na potrzeby Maps JavaScript API.

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

1. Otwórz konsolę Google Cloud.
2. Kliknij przycisk Wybierz projekt, a następnie wybierz ten sam projekt, który został skonfigurowany dla interfejsu Maps JavaScript API, i kliknij Otwórz.
3. Na liście interfejsów API w panelu znajdź Places API.
4. Jeśli interfejs API jest na liście, nie musisz nic więcej robić. Ten projekt ma jednak stan Starsza wersja. Więcej informacji o etapie starszej wersji i migracji ze starszej wersji do nowszych usług znajdziesz w artykule Starsze usługi i funkcje. Wyjątek dotyczy widżetów Autouzupełnianie i SearchBox, które nie są jeszcze dostępne jako usługa GA w interfejsie Places API (nowym).

Wczytywanie biblioteki

Usługa Places to samodzielna biblioteka, oddzielona od głównego kodu Maps JavaScript API. Aby korzystać z funkcji zawartych w tej bibliotece, musisz najpierw wczytać ją za pomocą parametru libraries w adresie URL wczytywania interfejsu API Map Google:

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

Więcej informacji znajdziesz w  omówieniu bibliotek.

Podsumowanie zajęć

Interfejs API oferuje 2 typy widżetów autouzupełniania, które możesz dodać, używając odpowiednio klas Autocomplete i SearchBox. Możesz też użyć klasy AutocompleteService, aby automatycznie pobierać wyniki autouzupełniania (zobacz dokumentację interfejsu Maps JavaScript API: klasa AutocompleteService).

Poniżej znajdziesz podsumowanie dostępnych klas:

• Autocomplete dodaje do strony internetowej pole do wprowadzania danych i sprawdza, czy wpisano w nim znaki. Gdy użytkownik wpisuje tekst, autouzupełnianie zwraca podpowiedzi miejsc w formie listy. Gdy użytkownik wybierze miejsce z listy, informacje o nim zostaną zwrócone do obiektu autouzupełniania i będą mogły zostać pobrane przez aplikację. Szczegółowe informacje znajdziesz poniżej.

  

  

• SearchBox dodaje pole do wprowadzania danych na stronie internetowej, podobnie jak Autocomplete. Różnice są następujące:
  • Główna różnica polega na wynikach, które pojawiają się na liście wyboru. SearchBox udostępnia rozszerzoną listę podpowiedzi, która może obejmować miejsca (zgodnie z definicją w Places API) oraz sugerowane wyszukiwane słowa. Jeśli na przykład użytkownik wpisze „pizza w now”, lista wyboru może zawierać wyrażenie „pizza w Nowym Jorku” oraz nazwy różnych pizzerii.
  • SearchBox oferuje mniej opcji ograniczania wyszukiwania niż Autocomplete. W pierwszym przypadku możesz ukierunkować wyszukiwanie na dany element LatLngBounds. W tym drugim przypadku możesz ograniczyć wyszukiwanie do konkretnego kraju i określonych typów miejsc, a także ustawić granice. Więcej informacji znajdziesz poniżej.

  

  Szczegółowe informacje znajdziesz poniżej.
• Możesz utworzyć obiekt AutocompleteService, aby pobierać prognozy automatycznie. Wywołaj getPlacePredictions(), aby pobrać pasujące miejsca, lub getQueryPredictions(), aby pobrać pasujące miejsca i sugerowane wyszukiwane hasła. Uwaga: AutocompleteService nie dodaje żadnych elementów sterujących interfejsu. Zamiast tego powyższe metody zwracają tablicę obiektów podpowiedzi. Każdy obiekt podpowiedzi zawiera tekst podpowiedzi, a także informacje referencyjne i szczegóły dotyczące dopasowania wyniku do danych wejściowych użytkownika. Szczegółowe informacje znajdziesz poniżej.

Dodawanie widżetu autouzupełniania

Widżet Autocomplete tworzy na stronie internetowej pole do wprowadzania danych, wyświetla podpowiedzi miejsc na liście wyboru w interfejsie i zwraca informacje o miejscu w odpowiedzi na żądanie getPlace(). Każdy wpis na liście wyboru odpowiada pojedynczemu miejscu (zgodnie z definicją w Places API).

Konstruktor Autocomplete przyjmuje 2 argumenty:

• Element HTML input typu text. To jest pole do wprowadzania danych, które usługa autouzupełniania będzie monitorować i do którego będzie dołączać wyniki.
• Opcjonalny argument AutocompleteOptions, który może zawierać te właściwości:
  • Tablica danych fields, które mają zostać uwzględnione w odpowiedzi Place Details dla wybranego przez użytkownika PlaceResult. Jeśli właściwość nie jest ustawiona lub przekazano wartość ['ALL'], zwracane są wszystkie dostępne pola i naliczane są za nie opłaty (nie jest to zalecane w przypadku wdrożeń produkcyjnych). Listę pól znajdziesz w artykule PlaceResult.
  • Tablica types, która określa konkretny typ lub kolekcję typów wymienionych w obsługiwanych typach. Jeśli nie podasz typu, zostaną zwrócone wszystkie typy.
  • bounds to obiekt google.maps.LatLngBounds określający obszar, na którym mają być wyszukiwane miejsca. Wyniki są ukierunkowane na miejsca znajdujące się w tych granicach, ale nie są do nich ograniczone.
  • strictBounds to boolean określający, czy interfejs API musi zwracać tylko te miejsca, które znajdują się ściśle w regionie zdefiniowanym przez dany bounds. Interfejs API nie zwraca wyników spoza tego regionu, nawet jeśli pasują do danych wejściowych użytkownika.
  • componentRestrictions można użyć, aby ograniczyć wyniki do określonych grup. Możesz użyć 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. Wiele krajów należy przekazać jako listę kodów krajów.

    Uwaga: jeśli otrzymasz nieoczekiwane wyniki z kodem kraju, sprawdź, czy używasz kodu, który obejmuje kraje, terytoria zależne i specjalne obszary geograficzne, które Cię interesują. Informacje o kodach znajdziesz w Wikipedii: Lista kodów krajów ISO 3166 lub na platformie przeglądania online ISO.

  • Za pomocą placeIdOnly można poinstruować widżet Autocomplete, aby pobierał tylko identyfikatory miejsc. Po wywołaniu metody getPlace() na obiekcie Autocomplete udostępniony obiekt PlaceResult będzie miał ustawione tylko właściwości place id, types i name. Zwróconego identyfikatora miejsca możesz używać w wywołaniach usług Places, Geocoding, Directions lub macierz odległości.

Ograniczanie podpowiedzi autouzupełniania

Domyślnie autouzupełnianie miejsc wyświetla wszystkie typy miejsc, faworyzując podpowiedzi w pobliżu lokalizacji użytkownika, i pobiera wszystkie dostępne pola danych dla wybranego przez użytkownika miejsca. Skonfiguruj opcje autouzupełniania miejsc, aby wyświetlać trafniejsze podpowiedzi na podstawie przypadku użycia.

Ustawianie opcji podczas tworzenia

Konstruktor Autocomplete akceptuje parametr AutocompleteOptions, aby ustawić ograniczenia podczas tworzenia widżetu. W tym przykładzie ustawiono opcje bounds, componentRestrictions i types, aby wysyłać żądania dotyczące miejsc typu establishment, faworyzując te, które znajdują się w określonym obszarze geograficznym, i ograniczając podpowiedzi tylko do miejsc w Stanach Zjednoczonych. Ustawienie opcji fields określa, jakie informacje o wybranym przez użytkownika miejscu mają być zwracane.

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

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,
};

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

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,
};
const autocomplete = new google.maps.places.Autocomplete(input, options);
index.js

Określanie pól danych

Określ pola danych, aby uniknąć opłat za SKU danych o miejscach, których nie potrzebujesz. Uwzględnij właściwość fields w AutocompleteOptions przekazywanych do konstruktora widżetu, jak pokazano w poprzednim przykładzie, lub wywołaj setFields() na istniejącym obiekcie Autocomplete.

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

Definiowanie uprzedzeń i granic obszaru wyszukiwania na potrzeby autouzupełniania

Możesz faworyzować wyniki autouzupełniania, aby preferować przybliżoną lokalizację lub obszar, na następujące sposoby:

• Ustaw granice podczas tworzenia obiektu Autocomplete.
• Zmień granice istniejącego elementu Autocomplete.
• Ustaw granice widocznego obszaru mapy.
• Ogranicz wyszukiwanie do granic.
• Ogranicz wyszukiwanie do określonego kraju.

W poprzednim przykładzie pokazaliśmy, jak ustawić granice podczas tworzenia. Poniższe przykłady pokazują inne techniki ukierunkowywania.

Zmiana granic istniejącego autouzupełniania

Wywołaj setBounds(), aby zmienić obszar wyszukiwania w istniejącym obiekcie Autocomplete na prostokątne granice.

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);
index.ts

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);
index.js

Ustawianie granic widocznego obszaru mapy

Użyj bindTo(), aby dostosować wyniki do widocznego obszaru mapy, nawet gdy ten obszar się zmienia.

autocomplete.bindTo("bounds", map);
index.ts

autocomplete.bindTo("bounds", map);
index.js

Użyj unbind(), aby odłączyć podpowiedzi autouzupełniania od widocznego obszaru mapy.

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

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

Zobacz przykład

Ogranicz wyszukiwanie do bieżących granic

Ustaw opcję strictBounds, aby ograniczyć wyniki do bieżących granic, niezależnie od tego, czy są one oparte na widocznym obszarze mapy czy na granicach prostokątnych.

autocomplete.setOptions({ strictBounds: true });

Ograniczanie podpowiedzi do określonego kraju

Użyj opcji componentRestrictions lub wywołaj setComponentRestrictions(), aby ograniczyć wyszukiwanie autouzupełniania do określonego zestawu maksymalnie 5 krajów.

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

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

Zobacz przykład

Ograniczanie typów miejsc

Użyj opcji types lub wywołaj setTypes(), aby ograniczyć podpowiedzi do określonych typów miejsc. To ograniczenie określa typ lub kolekcję typów wymienionych w sekcji Typy miejsc. Jeśli nie podano ograniczenia, zwracane są wszystkie typy.

Jako wartość opcji types lub wartość przekazywaną do setTypes() możesz podać:

• Tablica zawierająca maksymalnie 5 wartości z tabeli 1 lub tabeli 2 z sekcji Typy miejsc. Na przykład:

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

  Lub:

  autocomplete.setTypes(['hospital', 'pharmacy', 'bakery', 'country']);

• Dowolny filtr z tabeli 3 w sekcji Typy miejsc. Możesz podać tylko jedną wartość z tabeli 3.

Prośba zostanie odrzucona, jeśli:

• Określisz więcej niż 5 typów.
• określisz wszystkie nierozpoznane typy.
• Możesz połączyć dowolne typy z tabeli 1 lub tabeli 2 z dowolnym filtrem z tabeli 3.

Wersja demonstracyjna autouzupełniania miejsc pokazuje różnice w podpowiedziach między różnymi typami miejsc.

Obejrzyj wersję demonstracyjną

Uzyskiwanie informacji o miejscu

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

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

Domyślnie, gdy użytkownik wybierze miejsce, autouzupełnianie zwraca wszystkie dostępne pola danych dla wybranego miejsca, a Ty ponosisz odpowiednie opłaty. Użyj Autocomplete.setFields(), aby określić, które pola danych miejsca mają zostać zwrócone. Dowiedz się więcej o obiekcie PlaceResult, w tym o liście pól danych o miejscu, o które możesz poprosić. Aby uniknąć opłat za dane, których nie potrzebujesz, użyj parametru Autocomplete.setFields(), aby określić tylko te dane o miejscach, których będziesz używać.

Właściwość name zawiera description z podpowiedzi autouzupełniania miejsc. Więcej informacji o description znajdziesz w dokumentacji autouzupełniania miejsc.

W przypadku formularzy adresowych przydatne jest uzyskanie adresu w uporządkowanym formacie. Aby uzyskać uporządkowany adres wybranego miejsca, wywołaj Autocomplete.setFields() i określ pole address_components.

W poniższym przykładzie pola w formularzu adresu są wypełniane za pomocą autouzupełniania.

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();
}
index.ts

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;
index.js

Zobacz przykład

Dostosowywanie tekstu zastępczego

Domyślnie pole tekstowe utworzone przez usługę autouzupełniania zawiera standardowy tekst zastępczy. Aby zmienić 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 automatycznie lokalizowany. Jeśli określisz własną wartość zmiennej, musisz obsłużyć lokalizację tej wartości w aplikacji. Informacje o tym, jak interfejs Google Maps JavaScript API wybiera język, znajdziesz w dokumentacji dotyczącej lokalizacji.

Aby dostosować wygląd widżetu, zapoznaj się z artykułem Styling the Autocomplete and SearchBox widgets (Stylizowanie widżetów autouzupełniania i pola wyszukiwania).

Dodawanie widżetu SearchBox

SearchBox umożliwia użytkownikom wyszukiwanie geograficzne na podstawie tekstu, np. „pizza w Nowym Jorku” lub „sklepy obuwnicze w pobliżu ulicy Robson”. Możesz dołączyć SearchBox do pola tekstowego, a gdy tekst zostanie wpisany, usługa zwróci podpowiedzi w formie listy rozwijanej.

SearchBox udostępnia rozszerzoną listę podpowiedzi, która może obejmować miejsca (zgodnie z definicją w Places API) oraz sugerowane wyszukiwane słowa. Jeśli na przykład użytkownik wpisze „pizza w now”, lista wyboru może zawierać wyrażenie „pizza w Nowym Jorku” oraz nazwy różnych pizzerii. Gdy użytkownik wybierze miejsce z listy, informacje o nim zostaną zwrócone do obiektu SearchBox i będą mogły zostać pobrane przez aplikację.

Konstruktor SearchBox przyjmuje 2 argumenty:

• Element HTML input typu text. To jest pole do wprowadzania danych, które usługa SearchBox będzie monitorować i do którego będzie dołączać wyniki.
• Argument options, który może zawierać właściwość bounds: bounds to obiekt google.maps.LatLngBounds określający obszar, na którym mają być wyszukiwane miejsca. Wyniki są ukierunkowane na miejsca znajdujące się w tych granicach, ale nie ograniczają się do nich.

Poniższy kod używa parametru bounds, aby faworyzować wyniki dotyczące miejsc w określonym obszarze geograficznym, który jest określony za pomocą współrzędnych geograficznych.

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
});

Zmienianie obszaru wyszukiwania w polu wyszukiwania

Aby zmienić obszar wyszukiwania dla istniejącego obiektu SearchBox, wywołaj setBounds() na 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łuje zdarzenie places_changed. Możesz wywołać getPlaces() na obiekcie SearchBox, aby pobrać tablicę zawierającą kilka podpowiedzi, z których każda jest obiektem PlaceResult.

Więcej informacji o obiekcie PlaceResult znajdziesz w dokumentacji dotyczącej wyników szczegółowych informacji o miejscu.

// 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);
});
index.ts

// 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);
});
index.js

Zobacz przykład

Aby dostosować wygląd widżetu, zapoznaj się z artykułem Styling the Autocomplete and SearchBox widgets (Stylizowanie widżetów autouzupełniania i pola wyszukiwania).

Pobieranie prognoz usługi autouzupełniania miejsc automatycznie

Aby pobierać prognozy automatycznie, użyj klasy AutocompleteService. AutocompleteService nie dodaje żadnych elementów sterujących interfejsu. Zamiast tego zwraca tablicę obiektów podpowiedzi, z których każdy zawiera tekst podpowiedzi, informacje referencyjne i szczegóły dotyczące dopasowania wyniku do danych wejściowych użytkownika. Jest to przydatne, jeśli chcesz mieć większą kontrolę nad interfejsem użytkownika, niż oferują opisane powyżej Autocomplete i SearchBox.

AutocompleteService udostępnia te metody:

• getPlacePredictions() zwraca podpowiedzi miejsc. Uwaga: „miejsce” może być placówką, położeniem geograficznym lub ważnym punktem orientacyjnym, zgodnie z definicją w Places API.
• getQueryPredictions() zwraca rozszerzoną listę podpowiedzi, która może obejmować miejsca (zgodnie z definicją w Places API) oraz sugerowane wyszukiwane słowa. Jeśli na przykład użytkownik wpisze „pizza w now”, lista wyboru może zawierać wyrażenie „pizza w Nowym Jorku” oraz nazwy różnych pizzerii.

Obie powyższe metody zwracają tablicę obiektów podpowiedzi w takiej postaci:

• description to dopasowana podpowiedź.
• distance_meters to odległość w metrach od określonego miejsca AutocompletionRequest.origin.
• matched_substrings zawiera zbiór podłańcuchów w opisie, które pasują do elementów w danych wejściowych użytkownika. Jest to przydatne do wyróżniania tych podłańcuchów w aplikacji. W wielu przypadkach zapytanie będzie wyświetlane jako podłańcuch pola opisu.
  • length to długość podłańcucha.
  • offset to przesunięcie znaku mierzone od początku ciągu znaków opisu, w którym pojawia się dopasowany podłańcuch.
• place_id to identyfikator tekstowy, który jednoznacznie identyfikuje miejsce. Aby pobrać informacje o miejscu, przekaż ten identyfikator w polu placeId żądania szczegółów miejsca. Dowiedz się więcej o odwoływaniu się do miejsca za pomocą identyfikatora miejsca.
• terms to tablica zawierająca elementy zapytania. W przypadku miejsca każdy element zwykle stanowi część adresu.
  • offset to przesunięcie znaku mierzone od początku ciągu opisu, w którym pojawia się dopasowany podłańcuch.
  • value to pasujące hasło.

Poniższy przykład wykonuje żądanie podpowiedzi zapytania dla wyrażenia „pizza w pobliżu” i wyświetla wynik na liście.

// 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;
index.ts

// 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;
index.js

style.css

<html>
  <head>
    <title>Retrieving Autocomplete Predictions</title>

    <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 script 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. See
      https://developers.google.com/maps/documentation/javascript/load-maps-js-api
      for more information.
      -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initService&libraries=places&v=weekly"
      defer
    ></script>
  </body>
</html>
index.html

Zobacz przykład

Tokeny sesji

AutocompleteService.getPlacePredictions() może używać tokenów sesji (jeśli są zaimplementowane) do grupowania żądań autouzupełniania na potrzeby rozliczeń. Tokeny sesji grupują fazy zapytania i wyboru wyszukiwania z autouzupełnianiem przez użytkownika w osobną sesję na potrzeby rozliczeń. Sesja rozpoczyna się, gdy użytkownik zaczyna wpisywać zapytanie, a kończy, gdy wybiera miejsce. Każda sesja może obejmować wiele zapytań, po których następuje wybór jednego miejsca. Po zakończeniu sesji token traci ważność. Aplikacja musi generować nowy token dla każdej sesji. Zalecamy używanie tokenów sesji we wszystkich sesjach autouzupełniania. Jeśli parametr sessionToken zostanie pominięty lub jeśli ponownie użyjesz tokena sesji, sesja zostanie rozliczona tak, jakby nie podano tokena sesji (każde żądanie jest rozliczane osobno).

Użyj tego samego tokena sesji, aby wysłać jedno żądanie informacji o miejscu dotyczące miejsca, które jest wynikiem wywołania AutocompleteService.getPlacePredictions(). W takim przypadku żądanie autouzupełniania jest łączone z żądaniem informacji o miejscu, a wywołanie jest rozliczane jako zwykłe żądanie informacji o miejscu. Za żądanie autouzupełniania nie są pobierane żadne opłaty. Jeśli nie użyjesz tokena sesji w żądaniu, zostaną naliczone opłaty zarówno za żądanie autouzupełniania, jak i za żądanie informacji o miejscu.

Pamiętaj, aby przekazywać unikalny token sesji dla każdej nowej sesji. Użycie tego samego tokena w więcej niż 1 sesji autouzupełniania spowoduje unieważnienie tych sesji, a wszystkie żądania autouzupełniania w nieprawidłowych sesjach będą rozliczane indywidualnie przy użyciu SKU autouzupełniania na żądanie. Więcej informacji 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 uproszczenia):

// 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 przekazywać unikalny token sesji dla każdej nowej sesji. Użycie tego samego tokena w więcej niż jednej sesji spowoduje, że każde żądanie będzie rozliczane osobno.

Więcej informacji o tokenach sesji

Stylizowanie widżetów Autouzupełnianie i Pole wyszukiwania

Domyślnie elementy interfejsu udostępniane przez Autocomplete i SearchBox są stylizowane pod kątem umieszczenia na mapie Google. Możesz dostosować styl do swojej witryny. Dostępne są te klasy CSS. Wszystkie wymienione poniżej klasy dotyczą zarówno widżetu Autocomplete, jak i SearchBox.

Optymalizacja Autouzupełniania miejsc (starsza wersja)

W tej sekcji opisujemy sprawdzone metody, które pomogą Ci w pełni wykorzystać możliwości usługi autouzupełniania miejsc (starszej wersji).

Oto ogólne wskazówki:

• Najszybszym sposobem na stworzenie działającego interfejsu użytkownika jest użycie widżetu autouzupełniania miejsc (starsza wersja) z Maps JavaScript API, widżetu autouzupełniania miejsc (starsza wersja) z pakietu SDK Miejsc na Androida lub elementu sterującego interfejsu autouzupełniania miejsc (starsza wersja) z pakietu SDK Miejsc na iOS.
• Od samego początku poznaj najważniejsze pola danych Autouzupełniania miejsc (starsza wersja).
• Pola ukierunkowania na lokalizację i ograniczenia lokalizacji są opcjonalne, ale mogą mieć znaczący wpływ na działanie autouzupełniania.
• Użyj obsługi błędów, aby upewnić się, że aplikacja będzie działać prawidłowo, jeśli interfejs API zwróci błąd.
• Upewnij się, że aplikacja obsługuje sytuację, gdy nie ma wyboru, i oferuje użytkownikom sposób na kontynuowanie.

Sprawdzone metody optymalizacji kosztów

Podstawowa optymalizacja kosztów

Aby zoptymalizować koszty korzystania z usługi Autouzupełnianie miejsc (starsza wersja), użyj masek pól w widżetach Informacje o miejscu (starsza wersja) i Autouzupełnianie miejsc (starsza wersja), aby zwracać tylko te pola danych Autouzupełniania miejsc (starsza wersja), których potrzebujesz.

Zaawansowana optymalizacja kosztów

Rozważ automatyczne wdrożenie autouzupełniania miejsc (starsza wersja), aby uzyskać dostęp do SKU: Autouzupełnianie – cena za żądanie i poprosić o wyniki z interfejsu Geocoding API dotyczące wybranego miejsca zamiast informacji o miejscu (starsza wersja). Ceny za żądanie w połączeniu z Geocoding API są bardziej opłacalne niż ceny za sesję, jeśli spełnione są oba te warunki:

• Jeśli potrzebujesz tylko szerokości i długości geograficznej lub adresu miejsca wybranego przez użytkownika, interfejs Geocoding API dostarcza te informacje za mniejszą opłatą niż wywołanie interfejsu Place Details (starsza wersja).
• Jeśli użytkownicy wybierają podpowiedź autouzupełniania średnio w ciągu maksymalnie 4 żądań podpowiedzi autouzupełniania miejsc (starsza wersja), ceny za żądanie mogą być bardziej opłacalne niż ceny za sesję.

Czy Twoja aplikacja wymaga innych informacji niż adres i szerokość/długość geograficzna wybranej podpowiedzi?

Sprawdzone metody dotyczące skuteczności

Poniższe wytyczne opisują sposoby optymalizacji wydajności autouzupełniania miejsc (starsza wersja):

• Dodaj do implementacji Autouzupełniania miejsc (starszej wersji) ograniczenia związane z krajem, ustawienia lokalizacji i (w przypadku implementacji automatycznych) preferencje językowe. Ustawienia języka nie są potrzebne w przypadku widżetów, ponieważ pobierają one ustawienia języka z przeglądarki lub urządzenia mobilnego użytkownika.
• Jeśli autouzupełnianiu miejsc (starsza wersja) towarzyszy mapa, możesz ustawić preferencje lokalizacji według widocznego obszaru mapy.
• W sytuacjach, gdy użytkownik nie wybierze żadnej z podpowiedzi autouzupełniania miejsc (starsza wersja), zwykle dlatego, że żadna z nich nie jest adresem, którego szuka, możesz ponownie użyć pierwotnych danych wejściowych użytkownika, aby spróbować uzyskać trafniejsze wyniki:
  • Jeśli oczekujesz, że użytkownik wpisze tylko informacje o adresie, użyj ponownie oryginalnych danych wejściowych użytkownika w wywołaniu interfejsu Geocoding API.
  • Jeśli oczekujesz, że użytkownik będzie wpisywać zapytania dotyczące konkretnego miejsca według nazwy lub adresu, użyj żądania informacji o miejscu (starsza wersja). Jeśli wyniki są oczekiwane tylko w określonym regionie, użyj ustawienia lokalizacji.
  Inne scenariusze, w których najlepiej jest użyć Geocoding API:
  • Użytkownicy wpisują adresy podlokali, np. adresy konkretnych lokali lub mieszkań w budynku. Na przykład czeski adres „Stroupežnického 3191/17, Praha” zwraca częściową podpowiedź w Autouzupełnianiu miejsc (starsza wersja).
  • Użytkownicy wpisują adresy z prefiksami segmentów dróg, np. „23-30 29th St, Queens” w Nowym Jorku lub „47-380 Kamehameha Hwy, Kaneohe” na wyspie Kauai na Hawajach.

Uwzględnianie lokalizacji

Możesz faworyzować wyniki z określonego obszaru, przekazując parametry location i radius. Dzięki temu Autouzupełnianie miejsc (starsza wersja) będzie preferować wyświetlanie wyników w określonym obszarze. Wyniki spoza zdefiniowanego obszaru mogą być nadal wyświetlane. Możesz użyć parametru includedRegionCodes, aby filtrować wyniki i wyświetlać tylko miejsca w określonym kraju.

Ograniczanie lokalizacji

Ogranicz wyniki do określonego obszaru, przekazując parametr locationRestriction.

Możesz też ograniczyć wyniki do regionu określonego przez parametry location i radius, dodając parametr strictbounds. Dzięki temu autouzupełnianie miejsc (starsza wersja) zwraca tylko wyniki z tego regionu.

Limity wykorzystania

Limity

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