Автодополнение мест — это функция библиотеки Places в Maps JavaScript API. Вы можете использовать автодополнение, чтобы реализовать в своих приложениях функцию опережающего поиска, как в поле поиска Google Карт.
На этой странице объясняются различия между старыми и новыми функциями автозаполнения мест. В обеих версиях существует два основных способа интеграции автозаполнения:
- Программный интерфейс : для разработчиков, которым требуются более широкие возможности настройки и контроля над автозаполнением.
- Разместить виджет автозаполнения : панель поиска, которую можно встроить на карту или веб-страницу.
Программный интерфейс автозаполнения
В следующей таблице перечислены некоторые основные различия в использовании программного автозаполнения 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 позволяет программно получать подсказки автодополнения, обеспечивая больший контроль над пользовательским интерфейсом, чем класс 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 автозаполнения данных
- Пример прогнозирования данных автозаполнения места
- Пример сеансов автозаполнения данных
- Токены сеанса
-  Справочник интерфейса 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принимает два аргумента:-  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 предоставляет 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,
  });
}
- Документация по виджету автозаполнения (предварительная версия)
- Пример виджета автозаполнения
- Пример элемента автозаполнения
-  Ссылка на класс PlaceAutocompleteElement