Автозаполнение мест — это функция библиотеки Places в Maps JavaScript API. Вы можете использовать автозаполнение, чтобы дать своим приложениям поведение поиска с опережением ввода, как в поле поиска Google Maps.
На этой странице объясняются различия между устаревшими и новыми функциями Place Autocomplete. В обеих версиях есть два общих способа интеграции Autocomplete:
- Программный интерфейс : для разработчиков, которым нужна большая настраиваемость и контроль над автозаполнением.
- Разместить виджет автозаполнения : панель поиска, которую можно встроить на карту или веб-страницу.
Программный интерфейс автозаполнения
В следующей таблице перечислены некоторые основные различия в использовании программного автозаполнения Place между Places Autocomplete Service (устаревшей версией) и Autocomplete Data API (новым) :
PlacesService (устаревший) | Place (Новое) |
---|---|
Ссылка на службу автозаполнения мест | Ссылка на автозаполнение данных (новая) |
AutocompletionRequest | AutocompleteRequest |
AutocompleteService.getPlacePredictions | AutocompleteSuggestion.fetchAutocompleteSuggestions |
AutocompletePrediction | PlacePrediction |
Методы требуют использования обратного вызова для обработки объекта результатов и ответа PlacesServiceStatus . | Использует Promises и работает асинхронно. |
Методы требуют проверки 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);
}
- Программное получение прогнозов Place Autocomplete Service
- Пример автозаполнения места
- Сеансовые токены
-
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 автозаполнения данных
- Пример прогнозирования данных автозаполнения места
- Пример сеансов автозаполнения данных Place
- Сеансовые токены
- Ссылка на интерфейс
AutocompleteRequest
- Ссылка на класс
AutocompleteSuggestion
- Ссылка на класс
PlacePrediction
Разместить виджет автозаполнения
В следующей таблице перечислены некоторые основные различия в использовании виджетов автозаполнения между службой Places (устаревшей) и классом Place (новым):
Служба мест (устаревшая) | Место (Новое) |
---|---|
Класс Autocomplete для прогнозирования мест. | Класс PlaceAutocompleteElement для прогнозирования мест. |
Класс SearchBox для прогнозирования запросов. | Прогнозы запросов недоступны в классе Autocomplete . |
Локализуется только текст-заполнитель ввода по умолчанию. | Заполнитель для ввода текста, логотип списка прогнозов и прогнозы мест поддерживают региональную локализацию. |
Виджет использует setBounds() или autocomplete.bindTo() для ограничения (смещения) поиска указанными границами, а также strictBounds для ограничения результатов указанными границами. | Виджет использует свойство locationBias для смещения результатов в соответствии с указанными границами и свойство locationRestriction для ограничения поиска указанными границами. |
Виджеты можно интегрировать только с помощью стандартного элемента ввода HTML. | Виджет можно интегрировать с помощью стандартного элемента ввода HTML или элемента gmp-place-autocomplete . |
При использовании виджета пользователи могут запрашивать недопустимые данные (например, «bisneyland»); этот случай должен быть явно обработан. | Виджет будет возвращать результаты только для предоставленных предложений и не может отправлять запросы на произвольные значения; поэтому нет необходимости обрабатывать потенциально недействительные запросы. |
Возвращает устаревший экземпляр PlaceResult . | Возвращает экземпляр Place . |
Поля данных о месте задаются как параметры для объекта Autocomplete . | Поля данных места устанавливаются, когда пользователь делает выбор и вызывается fetchFields() . |
Ограничено фиксированным набором типов мест и полей данных о местах . | Доступ к расширенному выбору типов мест и полей данных о местах . |
Сравнение кодов (виджеты)
В этом разделе сравнивается код для автозаполнения, чтобы проиллюстрировать различия между устаревшим виджетом Place Autocomplete и новым элементом Place Autocomplete.
Разместить виджет автозаполнения (устаревший)
Служба Places предлагает два типа виджетов автозаполнения, которые можно добавить с помощью классов Autocomplete
и SearchBox
. Каждый вид виджета можно добавить на карту в качестве элемента управления картой или встроить непосредственно в веб-страницу. В следующем примере кода показано встраивание виджета Autocomplete
в качестве элемента управления картой.
- Конструктор виджета
Autocomplete
принимает два аргумента:- Элемент
input
HTML типаtext
. Это поле ввода, которое служба автозаполнения будет отслеживать и прикреплять к нему свои результаты. - Необязательный аргумент
AutocompleteOptions
, в котором можно указать дополнительные параметры для ограничения запроса.
- Элемент
- Чтобы задать границы, экземпляр
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 предлагает PlaceAutocompleteElement
, подкласс HTMLElement
, который предоставляет компонент пользовательского интерфейса, который можно добавить на карту в качестве элемента управления картой или встроить непосредственно в веб-страницу. В следующем примере кода показано встраивание виджета 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,
});
}
- Документация по виджету автозаполнения (предварительная версия)
- Пример виджета автозаполнения
- Пример элемента автозаполнения Place
- Ссылка на класс
PlaceAutocompleteElement