Функция автозаполнения мест (Place Autocomplete) — это возможность библиотеки Places в JavaScript API карт. Вы можете использовать автозаполнение, чтобы придать своим приложениям поведение поиска с автозаполнением, аналогичное полю поиска Google Maps.
На этой странице объясняются различия между устаревшими и новыми функциями автозаполнения мест. В обеих версиях существует два основных способа интеграции автозаполнения:
- Программный интерфейс : Для разработчиков, стремящихся к большей настройке и контролю над процессом автозаполнения.
- Разместите виджет автозаполнения : поисковую строку, которую можно встроить в карту или веб-страницу.
Программный интерфейс автозаполнения
В таблице ниже перечислены некоторые основные различия в использовании программного автозаполнения мест между службой автозаполнения мест (устаревшая версия) и API данных автозаполнения (новая версия) :
PlacesService (Legacy) | Place (Новое) |
|---|---|
| Справочник службы автозаполнения мест | Справочник по автозаполнению данных (новый). |
AutocompletionRequest | AutocompleteRequest |
AutocompleteService.getPlacePredictions | AutocompleteSuggestion.fetchAutocompleteSuggestions |
AutocompletePrediction | PlacePrediction |
Для работы этих методов требуется использование функции обратного вызова для обработки объекта результатов и ответа PlacesServiceStatus . | Использует промисы и работает асинхронно. |
Для работы методов требуется проверка PlacesServiceStatus . | Проверка состояния не требуется, можно использовать стандартную обработку ошибок. Подробнее . |
При создании экземпляра Autocomplete поля данных задаются в качестве параметров. | Поля данных устанавливаются позже, при вызове функции fetchFields() . |
Поддерживается прогнозирование запросов (только SearchBox ). | В классе Autocomplete функция прогнозирования запросов недоступна. |
| Ограничено фиксированным набором типов мест и полей данных о местах . | Доступ к расширенному выбору типов мест и полей данных о местах . |
Следующие параметры используются как устаревшими, так и новыми API автозаполнения:
Сравнение кода (программное)
В этом разделе сравнивается код автозаполнения, чтобы проиллюстрировать различия между службой Places и классом Place для программных интерфейсов.
Получить подсказки автозаполнения (устаревшая версия)
Устаревшая служба Places Service позволяет программно получать прогнозы автозаполнения, обеспечивая больший контроль над пользовательским интерфейсом, чем предлагает класс Autocomplete . В следующем примере выполняется один запрос для "par" с объектом AutocompletionRequest , состоящим из входного значения и набора границ для смещения прогноза. Пример возвращает список экземпляров AutocompletePrediction и отображает описание для каждого из них. Функция в примере также создает токен сессии и применяет его к запросу.
function init() {
const placeInfo = document.getElementById("prediction");
const service = new google.maps.places.AutocompleteService();
const placesService = new google.maps.places.PlacesService(placeInfo);
var sessionToken = new google.maps.places.AutocompleteSessionToken();
// Define request options.
let request = {
input: "par",
sessionToken: sessionToken,
bounds: {
west: -122.44,
north: 37.8,
east: -122.39,
south: 37.78,
},
}
// Display the query string.
const title = document.getElementById("title");
title.appendChild(
document.createTextNode('Place predictions for "' + request.input + '":'),
);
// Perform the query and display the results.
const displaySuggestions = function (predictions, status) {
// Check the status of the Places Service.
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 placeRequest = {
placeId: predictions[0].place_id,
fields: ["name", "formatted_address"],
};
placesService.getDetails(placeRequest, (place, status) => {
if (status == google.maps.places.PlacesServiceStatus.OK && place) {
placeInfo.textContent = `
First predicted place: ${place.name} at ${place.formatted_address}`
}
});
};
// Show the results of the query.
service.getPlacePredictions(request, displaySuggestions);
}
- Программное получение прогнозов сервиса автозаполнения мест
- Пример автозаполнения для размещения
- Токены сессии
- Справочник
AutocompletionRequest - Справочник
AutocompletePrediction
Получить подсказки автозаполнения (новое)
Новый класс Place также позволяет программно получать предсказания автозаполнения, обеспечивая больший контроль над пользовательским интерфейсом, чем это предлагает класс PlaceAutocompleteElement . В следующем примере выполняется один запрос для «par», при этом AutocompleteRequest содержит входное значение и набор границ для смещения предсказания. Пример возвращает список экземпляров placePrediction и отображает описание для каждого из них. Функция примера также создает токен сессии и применяет его к запросу.
async function init() {
let sessionToken = new google.maps.places.AutocompleteSessionToken();
// Define request options.
let request = {
input: "par",
sessionToken: sessionToken,
locationBias: {
west: -122.44,
north: 37.8,
east: -122.39,
south: 37.78,
},
};
// Display the query string.
const title = document.getElementById("title");
title.appendChild(
document.createTextNode('Place predictions for "' + request.input + '":'),
);
// Perform the query and display the results.
const { suggestions } =
await google.maps.places.AutocompleteSuggestion.fetchAutocompleteSuggestions(request);
const resultsElement = document.getElementById("results");
for (let suggestion of suggestions) {
const placePrediction = suggestion.placePrediction;
const listItem = document.createElement("li");
listItem.appendChild(
document.createTextNode(placePrediction.text.text),
);
resultsElement.appendChild(listItem);
}
// Show the first predicted place.
let place = suggestions[0].placePrediction.toPlace();
await place.fetchFields({
fields: ["displayName", "formattedAddress"],
});
const placeInfo = document.getElementById("prediction");
placeInfo.textContent = `
First predicted place: ${place.displayName} at ${place.formattedAddress}`
}
- Разместить API автозаполнения данных
- Пример автозаполнения прогнозов данных
- Пример размещения данных автозаполнения для сеансов
- Токены сессии
- Справочник по интерфейсу
AutocompleteRequest - Справочник по классу
AutocompleteSuggestion - Справочник по классу
PlacePrediction
Разместите виджет автозаполнения
В таблице ниже перечислены основные различия в использовании виджетов автозаполнения между сервисом Places (устаревшая версия) и классом Place (новая версия):
| Служба размещения (наследие) | Место (Новое) |
|---|---|
Класс Autocomplete для прогнозирования местоположения. | Класс PlaceAutocompleteElement для прогнозирования местоположения. |
Класс SearchBoxдля прогнозирования запросов. | В классе Autocomplete функция прогнозирования запросов недоступна. |
| Локализован только текст-заполнитель поля ввода по умолчанию. | Заполнитель для текстового поля, логотип в списке прогнозов и прогнозы местоположения поддерживают региональную локализацию. |
Виджет использует setBounds() или autocomplete.bindTo() для ограничения (смещения) поиска в заданные границы, а также strictBounds для ограничения результатов заданными границами. | Виджет использует свойство locationBias для смещения результатов в заданные границы, а свойство locationRestriction для ограничения поиска заданными границами. |
| Встраивание виджетов возможно только с помощью стандартного HTML-элемента input. | Виджет можно интегрировать с помощью стандартного HTML-элемента input или элемента gmp-place-autocomplete . |
| При использовании виджета пользователи могут запрашивать недопустимые данные (например, "bisneyland"); этот случай необходимо обрабатывать явно. | Виджет будет возвращать результаты только для предоставленных подсказок и не сможет отправлять запросы на произвольные значения; поэтому нет необходимости обрабатывать потенциально некорректные запросы. |
Возвращает устаревший экземпляр PlaceResult . | Возвращает экземпляр Place . |
Поля данных, в которые можно поместить данные, задаются в качестве параметров для объекта Autocomplete . | Поля данных для размещения элементов устанавливаются, когда пользователь делает выбор и вызывается fetchFields() . |
| Ограничено фиксированным набором типов мест и полей данных о местах . | Доступ к расширенному выбору типов мест и полей данных о местах . |
Сравнение кода (виджетов)
В этом разделе сравнивается код автозаполнения, чтобы проиллюстрировать различия между устаревшим виджетом Place Autocomplete и новым элементом Place Autocomplete.
Разместить виджет автозаполнения (устаревшая версия)
Сервис «Места» предлагает два типа виджетов автозаполнения, которые можно добавить с помощью классов Autocomplete и SearchBox . Каждый тип виджета можно добавить на карту в качестве элемента управления картой или встроить непосредственно в веб-страницу. Следующий пример кода демонстрирует встраивание виджета Autocomplete в качестве элемента управления картой.
- Конструктор виджета
Autocompleteпринимает два аргумента:- HTML-элемент
inputтипаtext. Это поле ввода, которое будет отслеживать служба автозаполнения и прикреплять к нему результаты. - Необязательный аргумент
AutocompleteOptions, позволяющий указать дополнительные параметры для ограничения запроса.
- HTML-элемент
- Для задания границ экземпляр
Autocompleteможно явно привязать к карте, вызвав методautocomplete.bindTo(). - Укажите поля данных для автозаполнения в соответствующих параметрах.
function initMap() {
const map = new google.maps.Map(document.getElementById("map"), {
center: { lat: 40.749933, lng: -73.98633 },
zoom: 13,
mapTypeControl: false,
});
const card = document.getElementById("pac-card");
const input = document.getElementById("pac-input");
const options = {
fields: ["formatted_address", "geometry", "name"],
strictBounds: false,
};
map.controls[google.maps.ControlPosition.TOP_LEFT].push(card);
const autocomplete = new google.maps.places.Autocomplete(input, options);
// Bind the map's bounds (viewport) property to the autocomplete object,
// so that the autocomplete requests use the current map bounds for the
// bounds option in the request.
autocomplete.bindTo("bounds", map);
const infowindow = new google.maps.InfoWindow();
const infowindowContent = document.getElementById("infowindow-content");
infowindow.setContent(infowindowContent);
const marker = new google.maps.Marker({
map,
anchorPoint: new google.maps.Point(0, -29),
});
autocomplete.addListener("place_changed", () => {
infowindow.close();
marker.setVisible(false);
const place = autocomplete.getPlace();
if (!place.geometry || !place.geometry.location) {
// User entered the name of a Place that was not suggested and
// pressed the Enter key, or the Place Details request failed.
window.alert("No details available for input: '" + place.name + "'");
return;
}
// If the place has a geometry, then present it on a map.
if (place.geometry.viewport) {
map.fitBounds(place.geometry.viewport);
} else {
map.setCenter(place.geometry.location);
map.setZoom(17);
}
marker.setPosition(place.geometry.location);
marker.setVisible(true);
infowindowContent.children["place-name"].textContent = place.name;
infowindowContent.children["place-address"].textContent =
place.formatted_address;
infowindow.open(map, marker);
});
}
- Разместить документацию с функцией автозаполнения
- Пример виджета автозаполнения для размещения
- Пример поля поиска мест
- Справочник по классу
Autocomplete
Разместить виджет автозаполнения (новый)
Класс Place предоставляет подкласс HTMLElement — PlaceAutocompleteElement , который предоставляет компонент пользовательского интерфейса, который можно добавить на карту в качестве элемента управления картой или встроить непосредственно в веб-страницу. В следующем примере кода показано встраивание виджета PlaceAutocompleteElement в качестве элемента управления картой.
Виджет автозаполнения мест был улучшен следующим образом:
- Виджет автозаполнения поддерживает региональную локализацию (включая языки с написанием справа налево) для текстового поля ввода, логотипа списка подсказок и подсказок местоположения.
- Улучшена доступность, включая поддержку программ чтения с экрана и взаимодействия с клавиатурой.
- Виджет автозаполнения возвращает новый класс
Placeдля упрощения обработки возвращаемого объекта. - Улучшена поддержка мобильных устройств и экранов небольшого размера.
- Повышенная производительность и улучшенное графическое оформление.
Ключевые отличия в реализации включают:
- Элемент
PlaceAutocompleteElementпредоставляет собственное поле ввода и вставляется на страницу непосредственно с помощью HTML или JavaScript (в отличие от использования существующего элемента ввода). - В классе
Autocompleteфункция прогнозирования запросов недоступна. - Объект
PlaceAutocompleteElementсоздается с помощьюPlaceAutocompleteElementOptions.- Поля данных для размещения указываются во время выбора (при вызове функции
fetchFields()).
- Поля данных для размещения указываются во время выбора (при вызове функции
- Задайте границы, используя параметр
locationBoundsилиlocationRestriction.
let map;
let marker;
let infoWindow;
async function initMap() {
// Request needed libraries.
const [{ Map }, { AdvancedMarkerElement }] = await Promise.all([
google.maps.importLibrary("marker"),
google.maps.importLibrary("places"),
]);
// Initialize the map.
map = new google.maps.Map(document.getElementById("map"), {
center: { lat: 40.749933, lng: -73.98633 },
zoom: 13,
mapId: "4504f8b37365c3d0",
mapTypeControl: false,
});
const placeAutocomplete =
new google.maps.places.PlaceAutocompleteElement({
locationRestriction: map.getBounds(),
});
placeAutocomplete.id = "place-autocomplete-input";
const card = document.getElementById("place-autocomplete-card");
card.appendChild(placeAutocomplete);
map.controls[google.maps.ControlPosition.TOP_LEFT].push(card);
// Create the marker and infowindow.
marker = new google.maps.marker.AdvancedMarkerElement({
map,
});
infoWindow = new google.maps.InfoWindow({});
// Add the gmp-select listener, and display the results on the map.
placeAutocomplete.addEventListener("gmp-select", async ( place ) => {
const place = event.placePrediction.toPlace();
await place.fetchFields({
fields: ["displayName", "formattedAddress", "location"],
});
// If the place has a geometry, then present it on a map.
if (place.viewport) {
map.fitBounds(place.viewport);
} else {
map.setCenter(place.location);
map.setZoom(17);
}
let content =
'<div id="infowindow-content">' +
'<span id="place-displayname" class="title">' +
place.displayName +
'</span><br />' +
'<span id="place-address">' +
place.formattedAddress +
'</span>' +
'</div>';
updateInfoWindow(content, place.location);
marker.position = place.location;
});
}
// Helper function to create an info window.
function updateInfoWindow(content, center) {
infoWindow.setContent(content);
infoWindow.setPosition(center);
infoWindow.open({
map,
anchor: marker,
shouldFocus: false,
});
}
- Разместить виджет автозаполнения (предварительная версия) документация
- Пример размещения виджета автозаполнения
- Пример размещения элемента автозаполнения
- Справочник по классу
PlaceAutocompleteElement