Wprowadzenie
Autouzupełnianie to funkcja biblioteki Miejsc Maps JavaScript API. Za pomocą autouzupełniania możesz określić, korzysta z funkcji wyszukiwania z wyprzedzeniem w polu wyszukiwania Map Google. Usługa autouzupełniania może dopasowywać całe słowa i podłańcuchy, nazwy miejsc, adresy oraz plus . Dzięki temu aplikacje mogą wysyłać zapytania w miarę wpisywania tekstu przez użytkownika, aby i dostarczają prognozy miejsc na bieżąco. Zgodnie z definicją zawartą w interfejsie Places API „miejsce” może to być instytucja, lokalizacja geograficzna lub ważna ciekawego miejsca.
Pierwsze kroki
Zanim użyjesz biblioteki Miejsca w Maps JavaScript API, upewnij się, w konsoli Google Cloud włączony jest interfejs Places API – projektu skonfigurowanego na potrzeby Maps JavaScript API.
Aby wyświetlić listę włączonych interfejsów API:
- Przejdź do Konsola Google Cloud.
- Kliknij przycisk Wybierz projekt, a potem wybierz ten sam skonfigurowany projekt. Maps JavaScript API i kliknij Otwórz.
- Na liście interfejsów API w panelu znajdź Places API.
- Jeśli interfejs API jest widoczny na liście, nie musisz nic robić. Jeśli interfejsu API nie ma na liście,
włącz:
- U góry strony wybierz WŁĄCZ API, aby wyświetlić Biblioteka. Możesz też w menu po lewej stronie wybierz opcję Biblioteka.
- Wyszukaj interfejs Places API, a następnie wybierz go z listę wyników.
- Kliknij WŁĄCZ. Gdy proces się zakończy, Interfejs Places API pojawi się na liście interfejsów API Panel.
Wczytuję bibliotekę
Usługa Miejsca to autonomiczna biblioteka, odrębna od głównej
Kod JavaScript API Map Google. Aby korzystać z zawartych w niej funkcji
w tej bibliotece, musisz najpierw wczytać ją za pomocą pakietu 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>
Zobacz Omówienie bibliotek, aby dowiedzieć się więcej.
Podsumowanie zajęć
Interfejs API udostępnia 2 typy widżetów autouzupełniania, które można dodawać za pomocą
Autocomplete
i SearchBox
.
Dodatkowo możesz użyć klasy AutocompleteService
do pobierania
wyniki autouzupełniania (zobacz dokumentację interfejsu Maps JavaScript API:
klasa AutocompleteService).
Poniżej znajduje się podsumowanie dostępnych zajęć:
-
Autocomplete
dodaje do strony internetowej pole do wprowadzania tekstu. i monitoruje to pole pod kątem wpisywanych znaków. Gdy użytkownik wpisuje tekst, autouzupełnianie zwraca podpowiedzi miejsc w formie listę rozwijaną. Gdy użytkownik wybierze miejsce z listy, informacje informacje o miejscu są zwracane do obiektu autouzupełniania i można je pobrać przez Twoją aplikację. Szczegółowe informacje znajdziesz poniżej.Rys. 1. Autouzupełnianie pola tekstowego i listy wyboru Rys. 2. Wypełniony formularz adresowy -
SearchBox
dodaje do strony internetowej pole do wprowadzania tekstu. tak samo jakAutocomplete
. Różnice są następujące:- Główna różnica polega na tym,
które pojawią się na liście wyboru.
SearchBox
– materiały rozszerzoną listę prognoz, która może zawierać miejsca (zgodnie z definicją interfejsu Places API) i sugerowanych wyszukiwanych haseł. Jeśli na przykład użytkownik wpisz „Nowa pizza”, lista wyboru może zawierać wyrażenie „pizza w Krakowie” a także nazwy różnych pizzy gniazdka elektryczne. SearchBox
oferuje mniej opcji niżAutocomplete
za ograniczenie wyszukiwania. W pierwszym przypadku może ukierunkować wyszukiwanie na określonyLatLngBounds
. W to ostatnie, można ograniczyć wyszukiwanie do konkretnego kraju i konkretnego typów miejsc i wyznaczać granice. Więcej informacji: poniżej.
Rysunek 3. Pole wyszukiwania zawiera wyszukiwane hasła i prognozy miejsc. - Główna różnica polega na tym,
które pojawią się na liście wyboru.
- Możesz utworzyć
AutocompleteService
obiekt do pobrania w sposób zautomatyzowany. Zadzwoń pod numergetPlacePredictions()
do pobierz pasujące miejsca lub zadzwoń pod numergetQueryPredictions()
, aby pobrać pasujące miejsca oraz sugerowane wyszukiwane hasła. Uwaga:AutocompleteService
nie dodaje żadnych elementów sterujących interfejsu. Zamiast tego powyższe metody zwracają tablicę obiektów prognozowania. Każdy obiekt prognozy zawiera tekst prognozy oraz odwołanie i szczegółowe informacje o tym, jak wynik pasuje do danych wejściowych użytkownika. Zobacz Więcej informacji znajdziesz poniżej.
Dodawanie widżetu autouzupełniania
Autocomplete
widżet tworzy na stronie internetowej pole do wprowadzania tekstu, dostarcza prognozy miejsc w interfejsie użytkownika
i zwraca szczegółowe informacje o miejscu w odpowiedzi na żądanie getPlace()
. Każda pozycja w
lista wyboru odpowiada pojedynczemu miejscu (zgodnie z definicją interfejsu Places API).
Konstruktor Autocomplete
przyjmuje 2 argumenty:
- Element HTML
input
typutext
. To jest pole do wprowadzania danych, które zapewnia autouzupełnianie będzie monitorować i dołączać swoje wyniki. - Opcjonalna wartość
AutocompleteOptions
, który może zawiera następujące właściwości:- Tablica danych
fields
, która ma zostać uwzględniona w odpowiedźPlace Details
na elementPlaceResult
wybrany przez użytkownika. Jeśli nie została skonfigurowana lub jeśli przekazano wartość['ALL']
, zwracane są wszystkie dostępne pola i rozliczany dla (niezalecane) w przypadku wdrożeń produkcyjnych). Listę pól znajdziesz tutaj:PlaceResult
. - Tablica
types
, która określa jawny typ lub kolekcję typów wymienione na liście obsługiwanych typów. Jeśli nie określisz typu, wszystkie typy . bounds
to obiektgoogle.maps.LatLngBounds
określający obszaru, w którym mają być szukane miejsca. Wyniki są stronnicze, ale nie tylko oraz o miejscach znajdujących się w tych granicach.strictBounds
ma statusboolean
określając, czy interfejs API może zwracać tylko miejsca, które znajdują się ściśle w regionie zdefiniowanym przez podaną wartośćbounds
. Interfejs API nie zwraca wyników spoza tego regionu, nawet jeśli zgadzały się z danymi wejściowymi.componentRestrictions
można użyć do ograniczenia wyników do: określonych grup. Obecnie możesz użyć opcjicomponentRestrictions
, by filtrować według maksymalnie 5 krajów. Kraje muszą być przekazywane jako kraj zgodny z normą ISO 3166-1 alfa-2 o dwuznakowym formacie w kodzie. Jako listę kodów krajów należy przekazać wiele krajów.Uwaga: jeśli otrzymasz nieoczekiwane wyniki z kodem kraju, sprawdź, że używasz kodu zawierającego kraje, terytoria zależne i specjalne interesujące Cię obszary. Informacje o kodzie znajdziesz na stronie Wikipedia: lista ISO Kody krajów 3166 lub ISO Online Browsing Platforma.
placeIdOnly
może służyć do przekazywania instrukcjiAutocomplete
, aby pobrać tylko identyfikatory miejsc. W trakcie rozmowygetPlace()
na obiekcieAutocomplete
,PlaceResult
będą mieć tylkoplace id
, Ustawiono właściwościtypes
iname
. Za pomocą zwróconego identyfikator miejsca z wywołaniami funkcji Miejsca, Geokodowanie, Trasa dojazdu lub Macierz odległości usług Google.
- Tablica danych
Ograniczanie podpowiedzi autouzupełniania
Domyślnie autouzupełnianie miejsc przedstawia wszystkie typy miejsc, stronnicze dla podpowiedzi w pobliżu lokalizację użytkownika i pobiera wszystkie dostępne pola danych dotyczące wybranego przez niego miejsca. Ustaw miejsce Opcje autouzupełniania pozwalające wyświetlać trafniejsze podpowiedzi na podstawie do Twojego przypadku użycia.
Ustaw opcje podczas budowy
Konstruktor Autocomplete
akceptuje konstrukcję AutocompleteOptions
do ustawiania ograniczeń podczas tworzenia widżetu. Ten przykład ustawia
Opcje: bounds
, componentRestrictions
i types
do
żądanie typu establishment
miejsc, faworyzując te z określonej lokalizacji geograficznej
i ograniczania prognoz tylko do miejsc w Stanach Zjednoczonych. Ustawienie wartości
Opcja fields
określa, jakie informacje o wybranym przez użytkownika miejscu mają być zwracane.
Wywołaj setOptions()
, aby zmienić wartość opcji dla 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, }; 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, }; 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 z Miejsc, których nie potrzebujesz. Umieść właściwość fields
w elemencie
AutocompleteOptions
, które są przekazywane do konstruktora widżetów, jak pokazano w poprzednim kroku.
lub wywołanie setFields()
w istniejącym obiekcie Autocomplete
.
autocomplete.setFields(["place_id", "geometry", "name"]);
Zdefiniuj uprzedzenia i granice obszarów wyszukiwania dla Autouzupełnianie
Możesz stronnić wyniki autouzupełniania, aby dawać pierwszeństwo wynikom autouzupełniania lokalizację lub obszar w następujący sposób:
- Wyznacz granice podczas tworzenia obiektu
Autocomplete
. - Zmień granice w istniejącym obiekcie
Autocomplete
. - Ustaw granice na potrzeby widocznego obszaru mapy.
- Ogranicz wyszukiwanie do granic.
- Ograniczyć wyszukiwanie do konkretnego kraju.
Poprzedni przykład pokazuje granice wyznaczania granic podczas tworzenia. Poniższe przykłady obrazują inne techniki promowania.
Zmiana granic istniejącej funkcji autouzupełniania
Zadzwoń pod numer setBounds()
, aby zmienić obszar wyszukiwania w istniejącej
Autocomplete
do 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);
Wyznacz granice w obszarze widocznym na mapie
Użyj funkcji bindTo()
, aby ukierunkować wyniki na obszar mapy,
nawet wtedy, gdy widoczny obszar się zmienia.
TypeScript
autocomplete.bindTo("bounds", map);
JavaScript
autocomplete.bindTo("bounds", map);
Użyj narzędzia unbind()
, aby usunąć powiązanie podpowiedzi autouzupełniania z widocznym obszarem mapy.
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 });
Ogranicz wyszukiwanie do bieżących granic
Ustaw opcję strictBounds
, aby ograniczyć wyniki do bieżących granic, zarówno na podstawie widocznego obszaru mapy, jak i prostokątnych granic.
autocomplete.setOptions({ strictBounds: true });
Ograniczanie prognoz do konkretnego kraju
Użyj opcji componentRestrictions
lub zadzwoń pod numer setComponentRestrictions()
, aby ograniczyć
autouzupełniania do określonego zestawu do pięciu krajów.
TypeScript
autocomplete.setComponentRestrictions({ country: ["us", "pr", "vi", "gu", "mp"], });
JavaScript
autocomplete.setComponentRestrictions({ country: ["us", "pr", "vi", "gu", "mp"], });
Typy miejsc ograniczeń
Użyj opcji types
lub wywołaj setTypes()
, aby ograniczyć
dla określonych typów miejsc. To ograniczenie określa typ lub kolekcję typów,
jak wymienione w sekcji Typy miejsc.
Jeśli nie określisz ograniczenia, zwracane są wszystkie typy.
W przypadku wartości opcji types
lub wartości przekazywanej do setTypes()
może określić:
Tablica zawierająca maksymalnie 5 wartości z tabeli 1 lub Tabela 2 z Typy miejsc. Na przykład:
types: ['hospital', 'pharmacy', 'bakery', 'country']
Lub:
autocomplete.setTypes(['hospital', 'pharmacy', 'bakery', 'country']);
- Dowolny filtr w tabeli 3 w sekcji Typy miejsc. Możesz określić tylko jedną wartość z tabeli 3.
Prośba zostanie odrzucona, jeśli:
- Podajesz więcej niż 5 typów.
- Określasz nierozpoznane typy.
- Możesz mieszać dowolne typy z tabeli 1 lub tabeli 2 z dowolnym filtr z tabeli 3.
Prezentacja autouzupełniania miejsc pokazuje różnice w prognozach między różnymi typami miejsc.
Pobieram informacje o miejscu
Gdy użytkownik wybierze miejsce z podpowiedzi dołączonych do autouzupełniania.
polu tekstowym, usługa uruchamia zdarzenie place_changed
. Aby znaleźć miejsce
szczegóły:
- Utwórz moduł obsługi zdarzeń dla zdarzenia
place_changed
i wywołaj funkcjęaddListener()
na obiekcieAutocomplete
, aby dodać moduł obsługi. - Zadzwoń pod numer
Autocomplete.getPlace()
w obiekcieAutocomplete
, aby pobraćPlaceResult
obiektu, którego można potem użyć, aby uzyskać więcej informacji o wybranym miejsce.
Gdy użytkownik wybierze miejsce, autouzupełnianie zwraca domyślnie wszystkie
danych dotyczących wybranego miejsca oraz naliczymy odpowiednie opłaty.
Użyj formatu Autocomplete.setFields()
w celu określenia pól danych dotyczących miejsc, które mają być zwracane. Przeczytaj więcej na temat
PlaceResult
, w tym listę pól danych o miejscach, które
o które możesz poprosić. Aby uniknąć płacenia za dane, których nie potrzebujesz, użyj parametru Autocomplete.setFields()
, aby określić
tylko dane o miejscu, których będziesz używać.
Właściwość name
zawiera
description
z podpowiedzi autouzupełniania w Miejscach Google. Więcej informacji na ten temat znajdziesz
description
w:
Miejsca
Dokumentacja autouzupełniania.
W przypadku formularzy adresowych najlepiej jest uzyskać adres w uporządkowanym formacie. Do
zwraca uporządkowany adres dla wybranego miejsca, wywołaj
Autocomplete.setFields()
i podaj pole address_components
.
Ten przykład korzysta z autouzupełniania do wypełnienia pól w adresie formularza.
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;
Dostosowywanie tekstu zastępczego
Domyślnie pole tekstowe utworzone przez usługę autouzupełniania zawiera
standardowy tekst zastępczy. Aby go zmodyfikować, ustaw parametr
Atrybut placeholder
w elemencie input
:
<input id="searchTextField" type="text" size="50" placeholder="Anything you want!">
Uwaga: domyślny tekst zastępczy jest lokalizowany automatycznie. Jeśli i określić własną wartość zmiennej, musisz obsłużyć ją w swojej aplikacji. Informacje na temat działania Map Google Interfejs API JavaScript wybiera język, który ma być używany. Zapoznaj się z dokumentacją na lokalizacji.
Aby dostosować wygląd widżetu, zobacz Zmienianie stylu widżetów Autouzupełnianie i Pole wyszukiwania.
Dodawanie widżetu SearchBox
SearchBox
umożliwia użytkownikom wykonanie tekstowych działań geograficznych
wyszukiwanie, na przykład „pizza w Krakowie” lub „sklep obuwniczy w pobliżu ronda”.
SearchBox
możesz dołączyć do pola tekstowego.
tekstu, usługa zwróci prognozy w
w postaci listy rozwijanej.
SearchBox
dostarcza rozszerzoną listę prognoz, które
może zawierać miejsca (zgodnie z definicją interfejsu Places API) oraz sugerowane wyszukiwanie
Google Cloud. Jeśli na przykład użytkownik wpisze „Nowa pizza”, lista wyboru może
Umieścić wyrażenie „pizza w Krakowie” a także nazwy różnych
pizzerii. Gdy użytkownik wybierze miejsce z listy,
informacje o tym miejscu są zwracane do obiektu SearchBox i można je
pobrane przez aplikację.
Konstruktor SearchBox
przyjmuje 2 argumenty:
- Element HTML
input
typutext
. To jest pole do wprowadzania danych, które usługaSearchBox
będzie monitorować, i dołączaj do niego jej wyniki. - Argument
options
, który może zawierać Właściwośćbounds
:bounds
ma statusgoogle.maps.LatLngBounds
określający obszar, na którym mają być szukane miejsca. Wyniki są ukierunkowane na miejsca w obrębie te granice.
Ten kod używa parametru granic do zniekształcania wyników w kierunku miejsc na danym obszarze geograficznym określonym za pomocą współrzędne geograficzne.
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 pola SearchBox
Aby zmienić obszar wyszukiwania w istniejącym SearchBox
, wywołaj
setBounds()
na obiekcie SearchBox
i przekaż metodę
odpowiedni obiekt LatLngBounds
.
Pobieram informacje o miejscu
Gdy użytkownik wybierze element z podpowiedzi powiązanych z wyszukiwaniem
usługa uruchamia zdarzenie places_changed
. Dostępne opcje
wywołaj funkcję getPlaces()
w obiekcie SearchBox
, aby
pobrania tablicy zawierającej kilka prognoz, z których każda jest
PlaceResult
obiekt.
Więcej informacji o obiekcie PlaceResult
znajdziesz tutaj:
dokumentacja
wyniki ze szczegółowymi informacjami o miejscu.
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); });
Aby dostosować wygląd widżetu, zobacz Zmienianie stylu widżetów Autouzupełnianie i Pole wyszukiwania.
Automatyczne pobieranie podpowiedzi usługi autouzupełniania miejsc
Aby automatycznie pobierać prognozy, użyj funkcji
AutocompleteService
zajęcia. AutocompleteService
nie dodaje żadnych elementów sterujących interfejsu. Zamiast tego zwraca tablicę prognozy
obiekty, z których każdy zawiera tekst prognozy, informacje o odwołaniach
i szczegółowe 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ż jest
oferowane przez Autocomplete
i SearchBox
opisane powyżej.
Funkcja AutocompleteService
ujawnia te metody:
getPlacePredictions()
zwraca prognozy dotyczące miejsc. Uwaga: „miejsce” może to być podmiot, położenie geograficzne lub widoczne ciekawe miejsce zdefiniowane w interfejsie Places API.getQueryPredictions()
zwraca rozszerzoną listę wartości prognozy, które mogą obejmować miejsca (zgodnie z definicją interfejsu Places API); a także sugerowane zapytania. Jeśli na przykład użytkownik wpisz „Nowa pizza”, lista wyboru może zawierać wyrażenie „pizza w Krakowie” a także nazwy różnych pizzerii.
Obie powyższe metody zwracają tablicę prognoza obiekty o takiej postaci:
description
to pasująca prognoza.distance_meters
to odległość miejsca od miejsca (w metrach) określony elementAutocompletionRequest.origin
.matched_substrings
zawiera zestaw podłańcuchów w polu który pasuje do elementów wpisanych przez użytkownika. Przydaje się to w przypadku te podłańcuchy 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ątek ciągu opisu, w którym dopasowany podłańcuch
place_id
to identyfikator tekstowy, który jednoznacznie identyfikuje danego miejsca. Aby pobrać informacje o miejscu, przekaż ten identyfikator w poleplaceId
elementu Szczegóły miejsca . Dowiedz się więcej o tym, oznaczyć miejsce jako odniesienie wraz z identyfikatorem miejsca.terms
to tablica zawierająca elementy zapytania. Dla: danego miejsca, każdy element będzie zwykle stanowił część adresu.offset
to przesunięcie znaku mierzone od początek ciągu opisu, w którym dopasowany podłańcuch- Pasujące hasło to
value
.
Poniższy przykład uruchamia żądanie prognozy zapytania dla wyrażenia „pizza w pobliżu” i wyświetli wynik w formie listy.
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> <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>
Zobacz próbkę
Tokeny sesji
AutocompleteService.getPlacePredictions()
mogą używać tokenów sesji (jeśli są zaimplementowane) do grupowania żądań autouzupełniania na potrzeby rozliczeń
w celach informacyjnych. Tokeny sesji grupują fazy zapytania i wyboru użytkownika
w odrębnej sesji autouzupełniania
w celach rozliczeniowych. Sesja
rozpoczyna się, gdy użytkownik rozpoczyna wpisywanie zapytania, i kończy, gdy użytkownik wybierze
miejsce. Każda sesja może zawierać kilka zapytań, a następnie wybrać jedno miejsce.
Po zakończeniu sesji token straci ważność. Aplikacja musi:
i generować nowy token dla każdej sesji. Zalecamy korzystanie z tokenów sesji
wszystkich sesji autouzupełniania. Jeśli parametr sessionToken
ma wartość
zostanie pominięta lub jeśli użyjesz tokena sesji ponownie, opłata za sesję zostanie naliczona tak, jakby nie była
token sesji (każde żądanie jest rozliczane osobno).
Możesz użyć tego samego tokena sesji, aby utworzyć
Szczegóły miejsca
w miejscu, które wynika z połączenia z numerem AutocompleteService.getPlacePredictions()
.
W takim przypadku żądanie autouzupełniania jest łączone z informacjami o miejscu.
, opłata za połączenie zostanie pobrana jak zwykłe żądanie informacji o miejscu. Za
o autouzupełnianie.
Pamiętaj, aby w przypadku każdej nowej sesji przekazać unikalny token sesji. Używanie tego samego tokena dla więcej niż jedna sesja autouzupełniania unieważnia te sesje, a wszystkie żądania w nieprawidłowych sesjach będzie naliczana pojedynczo za pomocą funkcji Autouzupełnianie Kod SKU na żądanie. Więcej informacji o tokenach sesji
Poniższy przykład pokazuje, jak utworzyć token sesji, a następnie przekazać go w
AutocompleteService
(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 w przypadku każdej nowej sesji przekazać unikalny token sesji. Używanie tego samego dla więcej niż jednej sesji spowoduje naliczenie opłaty za każde żądanie. poszczególne osoby.
Więcej informacji o tokenach sesji
Wybieranie stylu widżetów autouzupełniania i pola wyszukiwania
Domyślnie elementy interfejsu udostępniane przez usługi Autocomplete
i
Obiekty SearchBox
zostały zaprojektowane tak, by można było uwzględnić je na mapie Google. Więcej informacji
aby dostosować styl do swojej strony. Te klasy CSS są
i dostępności informacji. Wszystkie wymienione poniżej zajęcia dotyczą zarówno
Autocomplete
i widżety SearchBox
.
![Graficzna ilustracja klas CSS dla funkcji autouzupełniania i
Widżety SearchBox](https://developers-dot-devsite-v2-prod.appspot.com/static/maps/documentation/javascript/images/place-autocomplete-css-diagram.png?authuser=4&hl=pl)
Klasa CSS | Opis |
---|---|
pac-container |
Element wizualny zawierający listę prognoz zwróconych przez
Usługa autouzupełniania miejsca. Jest ona wyświetlana w formie listy rozwijanej pod
Widżet Autocomplete lub SearchBox . |
pac-icon |
Ikona wyświetlana po lewej stronie każdego elementu na liście i generowanie prognoz. |
pac-item |
Element na liście prognoz dostarczanych przez
Widżet Autocomplete lub SearchBox . |
pac-item:hover |
Element, który pojawia się, gdy użytkownik najedzie na niego wskaźnikiem myszy. |
pac-item-selected |
Element, który użytkownik wybiera za pomocą klawiatury. Uwaga: wybrane elementy
będzie członkiem tych zajęć oraz tych, które należą do grupy pac-item .
|
pac-item-query |
Rozpiętość wewnątrz elementu pac-item , który jest główną częścią
z prognozą. W przypadku lokalizacji geograficznych zawiera ona nazwę miejsca, np.
„Gdańsk” lub nazwa ulicy i numer, na przykład „ul. Klejńska 10”. Dla:
wyszukiwania tekstowe, takie jak „pizza w Krakowie”, zawiera cały tekst
danego zapytania. Domyślnie kolor pac-item-query jest kolorowy.
czarnych. Jeśli pac-item zawiera dodatkowy tekst, jest on
poza pac-item-query i dziedziczy styl z
pac-item Domyślnie jest on w kolorze szarym. Dodatkowy tekst
jest zwykle adresem. |
pac-matched |
Część zwróconej prognozy, która pasuje do danych wejściowych użytkownika. Według
domyślnie, pasujący tekst zostanie pogrubiony. Pamiętaj, że parametr
dopasowany tekst może znajdować się w dowolnym miejscu w obrębie pac-item . Nie
musi być częścią usługi pac-item-query i może być częściowo
w pac-item-query , jak również częściowo w pozostałej części tekstu
w aplikacji pac-item . |
Użycie komponentu Selektor miejsc
Uwaga: ten przykład korzysta z biblioteki typu open source. Zobacz README w celu uzyskania pomocy i przekazują opinie związane z biblioteką.
Wypróbuj komponenty sieciowe. Należy użyć funkcji Komponent internetowy selektora miejsc, który umożliwia wprowadzanie tekstu, dzięki czemu użytkownicy mogą wyszukać konkretny adres lub miejsce przy użyciu autouzupełniania.
![GIF z polem wyszukiwania. Użytkownik zaczyna wpisywać adres jako dane wejściowe i w menu z powiązanymi
adresów. Użytkownik klika adres w menu i wypełnia pole wyszukiwania.
w pozostałej części adresu.](https://developers-dot-devsite-v2-prod.appspot.com/static/maps/documentation/javascript/images/place-picker.gif?authuser=4&hl=pl)
Optymalizacja miejsca autouzupełniania
W tej sekcji znajdziesz sprawdzone metody, które pomogą Ci w pełni wykorzystać Usługa autouzupełniania miejsca.
Oto kilka ogólnych wskazówek:
- Najszybszym sposobem na stworzenie działającego interfejsu użytkownika jest wykorzystanie Maps JavaScript API – widżet autouzupełniania, Widżet autouzupełniania Miejsc Google na Androida, lub pakietu SDK Miejsc dla systemu iOS elementów sterujących w interfejsie autouzupełniania
- Omówienie najważniejszych zasad autouzupełniania miejsc pola danych.
- Pola promowania lokalizacji i ograniczenia lokalizacji są opcjonalne, ale mogą mają istotny wpływ na działanie autouzupełniania.
- Zapewnianie płynnego pogorszenia stanu aplikacji dzięki obsłudze błędów jeśli interfejs API zwróci błąd.
- Upewnij się, że aplikacja działa, gdy nie ma możliwości wyboru, i daje użytkownikom możliwość aby kontynuować.
Sprawdzone metody optymalizacji kosztów
Podstawowa optymalizacja kosztów
Optymalizacja kosztów korzystania z autouzupełniania miejsc należy używać masek pól w widżetach Szczegóły miejsca i autouzupełniania, aby zwracać tylko rozmieść pola danych, których potrzebujesz.
Zaawansowana optymalizacja kosztów
Rozważ zautomatyzowaną implementację autouzupełniania miejsc, aby uzyskać dostęp do cen na żądanie i wysyłać żądania wyników interfejsu Geocoding API dotyczących wybranego miejsca zamiast szczegółów miejsca. Model cenowy za żądanie w połączeniu z interfejsem Geocoding API jest bardziej opłacalny niż model cenowy za sesję (na podstawie sesji), jeśli spełnione są oba te warunki:
- Jeśli potrzebujesz tylko szerokości i długości geograficznej lub adresu wybranego przez użytkownika miejsca, interfejs Geocoding API dostarcza te informacje dla mniej niż wywołania Place Details.
- Jeśli użytkownicy wybiorą podpowiedź autouzupełniania w zakresie nie więcej niż 4 żądań podpowiedzi autouzupełniania, model cenowy za żądanie może być bardziej opłacalny niż model płatności za sesję.
Czy aplikacja wymaga innych informacji poza adresem i szerokością geograficzną wybranej prognozy?
Tak, potrzebujemy więcej informacji
Korzystaj z autouzupełniania miejsc opartego na sesji, korzystając z szczegółów miejsca.
Twoja aplikacja wymaga informacji o miejscach, takich jak nazwa miejsca, status firmy lub godziny otwarcia, dlatego wdrożenie autouzupełniania miejsc powinno korzystać z tokena sesji (automatycznie lub wbudowanego w widżety JavaScript, Androida lub iOS.Ich łączny koszt wynosi 0,017 USD za sesję i dodatkowe kody SKU danych miejsc w zależności od tego, o jakie pola danych miejsc prosisz}.
Implementacja widżetu
Zarządzanie sesjami jest automatycznie wbudowane w widżety JavaScript oraz Android i iOS. Obejmuje to zarówno żądania autouzupełniania miejsc, jak i żądania szczegółów miejsca dotyczące wybranej prognozy. Określ parametr fields
, aby mieć pewność, że żądania są wysyłane wyłącznie
umieścić w odpowiednim miejscu pola danych.
Implementacja automatyczna
W żądaniach autouzupełniania miejsc używaj tokena sesji. W żądaniu Szczegóły miejsca dotyczące wybranej prognozy podaj te parametry:
- identyfikator miejsca z odpowiedzi na autouzupełnianie miejsca,
- Token sesji używany w żądaniu autouzupełniania miejsca.
- Parametr
fields
określający rozmieść pola danych, których potrzebujesz,
Nie, wymaga tylko adresu i lokalizacji
Interfejs Geocoding API może być tańszą opcją niż informacje o miejscu, w zależności od tego, jak dobrze korzystasz z autouzupełniania. Skuteczność autouzupełniania każdej aplikacji różni się w zależności od tego, co wpisują użytkownicy, gdzie aplikacja jest używana i czy wdrożone zostały sprawdzone metody dotyczące optymalizacji wydajności.
Aby odpowiedzieć na poniższe pytanie, przed wybraniem podpowiedzi autouzupełniania miejsca w aplikacji sprawdź, ile znaków średnio wpisuje użytkownik.
Czy użytkownicy wybierają podpowiedzi autouzupełniania miejsca średnio w przypadku 4 żądań lub mniejszej liczby żądań?
Tak
Zaimplementuj autouzupełnianie miejsc automatycznie bez tokenów sesji i wywołuj interfejs Geocoding API dla prognozy wybranego miejsca.
Geocoding API dostarcza adresy oraz współrzędne szerokości i długości geograficznej za 0,005 USD na żądanie. Utworzenie 4 żądań typu Place Autocomplete – Per Request (Autouzupełnianie – według żądania) kosztuje 0,01132 USD, więc łączny koszt 4 żądań plus wywołania Geocoding API dla wybranej prognozy miejsca wynosi 0,01632 USD, czyli mniej niż cena autouzupełniania na sesję, która wynosi 0,017 USD za sesję1.
Zastanów się nad skorzystaniem ze sprawdzonych metod dotyczących skuteczności, aby pomóc użytkownikom uzyskać podpowiedzi, których szukają, przy użyciu jeszcze mniejszej liczby znaków.
Nie
Korzystaj z autouzupełniania miejsc opartego na sesji, korzystając z szczegółów miejsca.
Średnia liczba spodziewanych żądań, zanim użytkownik wybierze prognozę autouzupełniania miejsca, przekracza koszt ceny za sesję, dlatego Twoja implementacja autouzupełniania miejsc powinna korzystać z tokena sesji zarówno dla żądań autouzupełniania miejsc, jak i powiązanych z nimi żądań informacji o miejscach.Całkowity koszt tych żądań wynosi więc 0,017 USD za sesję1.
Implementacja widżetu
Zarządzanie sesjami jest automatycznie wbudowane w widżety JavaScript oraz Android i iOS. Obejmuje to zarówno żądania autouzupełniania miejsc, jak i żądania szczegółów miejsca dotyczące wybranej prognozy. Pamiętaj, by określić parametr fields
, aby mieć pewność, że żądanie dotyczy tylko pól danych podstawowych.
Implementacja automatyczna
W żądaniach autouzupełniania miejsc używaj tokena sesji. W żądaniu Szczegóły miejsca dotyczące wybranej prognozy podaj te parametry:
- identyfikator miejsca z odpowiedzi na autouzupełnianie miejsca,
- Token sesji używany w żądaniu autouzupełniania miejsca.
- Parametr
fields
określający pola Dane podstawowe, takie jak adres i geometria
Rozważ opóźnienie prośby o autouzupełnianie miejsc
Aby zmniejszyć liczbę żądań, możesz zastosować strategie, takie jak opóźnienie żądania autouzupełniania miejsca do czasu wpisania przez użytkownika pierwszych trzech lub czterech znaków. Na przykład wykonywanie żądań autouzupełniania miejsc dla każdego znaku po wpisaniu trzeciego znaku przez użytkownika oznacza, że jeśli użytkownik wpisze 7 znaków, a potem wybierze prognozę, dla której utworzysz jedno żądanie do interfejsu Geocoding API, łączny koszt wyniesie 0,01632 USD (4 * 0,00283 Autouzupełniaj na żądanie + 0,005 USD za kodowanie geograficzne)1.
Jeśli opóźnienie żądań może spowodować, że średnia liczba żądań automatyzacji spadnie poniżej 4, postępuj zgodnie ze wskazówkami dotyczącymi skutecznej implementacji autouzupełniania miejsc za pomocą interfejsu Geocoding API. Pamiętaj, że opóźnienie żądań może być postrzegane jako opóźnienie przez użytkownika, który może oczekiwać podpowiedzi po każdym naciśnięciu klawisza.
Zastanów się nad skorzystaniem ze sprawdzonych metod dotyczących skuteczności, aby pomóc użytkownikom uzyskać spodziewaną prognozę przy użyciu mniejszej liczby znaków.
-
Podane tu koszty są podane w dolarach amerykańskich. Pełne ceny znajdziesz na stronie płatności za Google Maps Platform.
Sprawdzone metody zwiększania skuteczności
Poniższe wskazówki opisują sposoby optymalizacji skuteczności autouzupełniania miejsc:
- Dodaj ograniczenia związane z krajem, promowanie lokalizacji, (w przypadku implementacji automatycznych) ustawienia języka na autouzupełnianie miejsc. implementacji. Nie musisz wybierać języka dzięki widżetom, które wybierają język z przeglądarki użytkownika lub urządzenia mobilnego.
- Jeśli wraz z mapą jest wyświetlana mapa, możesz dostosować lokalizację według widocznego obszaru mapy.
- Jeśli użytkownik nie wybierze żadnej z podpowiedzi autouzupełniania,
ponieważ żadne z tych podpowiedzi nie są pożądanym adresem wynikowym, możesz ponownie użyć oryginalnego adresu
dane wejściowe użytkownika, aby uzyskać trafniejsze wyniki:
- Jeśli spodziewasz się, że użytkownik wpisze tylko informacje adresowe, użyj tych samych danych wejściowych co użytkownik w wywołaniu Geocoding API.
- Jeśli spodziewasz się, że użytkownicy będą wpisywać zapytania dotyczące konkretnego miejsca po nazwie lub adresie, skorzystaj z prośby o znajdowanie miejsca. Jeśli oczekiwane wyniki dotyczą tylko konkretnego regionu, użyj funkcji promowanie lokalizacji.
- Użytkownicy podający adresy podrzędne w krajach, w których autouzupełnianie obsługuje adresy obiektów podrzędnych są niekompletne, np. Czechy, Estonia i Litwa. Na przykład parametr Adres czeski „Stroupežnického 3191/17, Praha” daje częściową prognozę w miejscu Autouzupełnianie.
- użytkownicy, którzy wpisują adresy z prefiksami fragmentu drogi, np. „23–30 29th St, Wrocław”; cale New York City lub „47-380 Kamehameha Hwy, Kaneohe” na wyspie Kauai na Hawajach.
Limity i zasady użytkowania
Limity
Informacje o limitach i cenach znajdziesz w Dokumentacja korzystania z usługi i rozliczeń do interfejsu Places API.
Zasady
Korzystanie z Biblioteki miejsc, Maps JavaScript API musi być zgodne z opisanych zasad dla interfejsu Places API.