Как перейти на Places UI Kit, если вы уже используете Places API

Узнайте, как перенести существующую реализацию Places API или класса Place на компоненты Places UI Kit.

Для кого это руководство

Это руководство предназначено для разработчиков, которые уже используют Places API и хотят обновить свой код, чтобы использовать Places UI Kit. Этот курс будет наиболее полезен, если вы уже:

  • Отправка HTTP-запросов к конечным точкам Places API (нового или устаревшего).
  • Использование класса Place в Maps JavaScript API.
  • Обработка ответа API для отображения информации о месте в интерфейсе веб-приложения.

Требования

Включите Places UI Kit в своем облачном проекте Google Cloud. Вы можете использовать существующий ключ API или сгенерировать новый для Places UI Kit. Подробнее об использовании ключей API, в том числе об их ограничении…

Обновите загрузку Maps JavaScript API

Для Places UI Kit требуется метод загрузки Maps JavaScript API Dynamic Library Import. Если вы используете тег для прямой загрузки скрипта, его нужно обновить.

Обновив скрипт загрузки для Maps JavaScript API, импортируйте необходимые библиотеки, чтобы использовать Places UI Kit.

Как реализовать элемент Place Details

Элемент Place Details и компактный элемент Place Details – это элементы HTML, которые отображают информацию о месте.

Текущая реализация

  • Вы запрашиваете информацию о местах с помощью HTTP-запроса или используете класс Place в JavaScript API.
  • Вы анализируете ответ API и показываете информацию о месте с помощью HTML и CSS.

Переход на элемент "информация о местах"

Изменение структуры HTML

Определите HTML-контейнер, в котором отображается информация о местах. Замените собственные элементы HTML (div, span для названия, адреса, фотографий и т. д.) на HTML-код элемента информации о местах.

Вы можете выбрать один из двух элементов:

  • Компактный элемент с информацией о месте
  • Элемент "информация о местах"

Подробнее о том, какой из них использовать, читайте в статье Элемент Place Details.

Ваш HTML-код может выглядеть следующим образом:

<div id="my-place-details-container">
    <h2 id="place-name"></h2>
    <p id="place-address"></p>
    <img id="place-photo" src="" alt="Place photo">
    <!-- ... more custom elements -->
</div>

Пример нового HTML-кода, в котором явно указано, какой контент нужно показывать:

<gmp-place-details-compact orientation="horizontal" truncation-preferred style="display: none;">
    <gmp-place-details-place-request></gmp-place-details-place-request>
    <gmp-place-content-config>
        <gmp-place-media lightbox-preferred></gmp-place-media>
        <gmp-place-address></gmp-place-address>
        <gmp-place-rating></gmp-place-rating>
        <gmp-place-type></gmp-place-type>
        <gmp-place-price></gmp-place-price>
        <gmp-place-accessible-entrance-icon></gmp-place-accessible-entrance-icon>
        <gmp-place-open-now-status></gmp-place-open-now-status>
    </gmp-place-content-config>
</gmp-place-details-compact>

Адаптация логики JavaScript

Существующая логика

Существующая логика, скорее всего, включает:

  • Получение идентификатора места.
  • Использование PlacesService().getDetails() или вызов веб-сервиса.
  • Укажите массив полей (для JS API) или FieldMask (для веб-сервиса), чтобы запросить определенные данные.
  • В решении с обратным вызовом вручную выберите элементы HTML и заполните их полученными данными.

Ниже приведен пример реализации информации о местах.

async function getPlaceDetails(placeId) {
    const { Place } = await google.maps.importLibrary('places');
    // Use place ID to create a new Place instance.
    const place = new Place({
        id: placeId
    });
    await place.fetchFields({
        fields: ['displayName', 'formattedAddress', 'location'],
    });
    // Log the result
    console.log(place.displayName);
    console.log(place.formattedAddress);
}
Новая логика

Новая логика будет включать:

  • Получите идентификатор или объект места.
  • Получите ссылку на элемент <gmp-place-details-place-request>.
  • Передайте идентификатор места или объект места в свойство place элемента <gmp-place-details-place-request>.

Ниже приведен пример того, как можно реализовать набор интерфейса "Информация о местах" в логике JavaScript. Получите ссылку на элемент Place Details. Если он существует, получите ссылку на элемент Place Request в Place Details и задайте свойство места с помощью идентификатора места. В примере HTML-кода выше для стиля элемента сведений о месте задано значение display: none. Теперь это display: block.

function displayPlaceDetailsWithUIKit(placeId) {
  const placeDetailsElement = document.querySelector('gmp-place-details-compact');
  if (placeDetailsElement) {
    const placeDetailsRequest = document.querySelector('gmp-place-details-place-request');
    // Configure the element with the Place ID
    placeDetailsRequest.place = placeId
    placeDetailsElement.style.display = 'block';
    console.log("PlaceDetailsElement configured for place:", placeId);
  } else {
    console.error("PlaceDetailsElement not found in the DOM.");
  }
}

// Example usage:
const placeId = 'ChIJC8HakaIRkFQRiOgkgdHmqkk';
displayPlaceDetailsWithUIKit(placeId);

Элемент поиска мест – это элемент HTML, который показывает результаты поиска мест в виде списка.

  • Вы выполняете текстовый поиск или поиск поблизости с помощью HTTP-запроса или класса Place в JavaScript API.
  • Вы указываете параметры запроса, ограничения или смещения местоположения, типы и запрашиваемые поля с помощью FieldMask.
  • Вы анализируете ответ API, перебираете массив мест и вручную создаете элементы списка HTML.

Изменение структуры HTML

Определите HTML-контейнер, в котором будет отображаться список Ваших мест. Замените собственные элементы HTML (div, span для названия, адреса и т. д.) на элемент HTML поиска мест.

Ваш HTML-код может выглядеть примерно так:

<div id="search-results-area">
    <h3>Nearby Places:</h3>
    <ul id="manual-places-list">
        <!-- JavaScript would dynamically insert list items here -->
        <!-- Example of what JS might generate:
    <li class="place-entry" data-place-id="SOME_PLACE_ID_1">
      <img class="place-icon" src="icon_url_1.png" alt="Icon">
      <span class="place-name">Place Name One</span> -
      <span class="place-vicinity">123 Main St</span>
    </li>
    <li class="place-entry" data-place-id="SOME_PLACE_ID_2">
      <img class="place-icon" src="icon_url_2.png" alt="Icon">
      <span class="place-name">Place Name Two</span> -
      <span class="place-vicinity">456 Oak Ave</span>
    </li>
    -->
        <li class="loading-message">Loading places...</li>
    </ul>
</div>

Элемент поиска мест реализован с помощью компонента <gmp-place-search>. Чтобы настроить тип поиска, включите внутрь один из следующих компонентов конфигурации:

  • <gmp-place-text-search-request> для текстового поиска.
  • <gmp-place-nearby-search-request> за поиск поблизости.

Чтобы определить, как будут показываться результаты, вы можете использовать ярлык <gmp-place-all-content> или предоставить собственный набор отдельных компонентов представления. Основные атрибуты, такие как selectable (чтобы разрешить клики по элементам списка) и orientation (для горизонтального или вертикального макета), можно задать непосредственно в родительском компоненте.

Пример поиска поблизости
<gmp-place-search orientation="horizontal" selectable>
    <gmp-place-all-content> </gmp-place-all-content>
    <gmp-place-nearby-search-request></gmp-place-nearby-search-request>
</gmp-place-search>
Пример текстового поиска
<gmp-place-search orientation="horizontal" selectable>
  <gmp-place-all-content> </gmp-place-all-content>
  <gmp-place-text-search-request></gmp-place-text-search-request>
</gmp-place-search>

Адаптация логики JavaScript

В коде JavaScript получите ссылку на компонент контроллера поиска с помощью document.querySelector(). В зависимости от настроек это будет элемент <gmp-place-text-search-request> или <gmp-place-nearby-search-request>.

Затем задайте свойства этого контроллера, чтобы определить поиск. Необходимые свойства зависят от типа выполняемого поиска.

Для текстового поиска (<gmp-place-text-search-request>) основным свойством является textQuery:

const textSearchController = document.querySelector('gmp-place-text-search-request');
textSearchController.textQuery = 'museums in London';

Для поиска мест рядом (<gmp-place-nearby-search-request>) необходимо определить область поиска с помощью locationRestriction. Затем с помощью includedTypes можно отфильтровать места определенного типа в этой области:

const nearbySearchController = document.querySelector('gmp-place-nearby-search-request');
nearbySearchController.locationRestriction = new google.maps.Circle({
    center: { lat: 51.5190, lng: -0.1347 },
    radius: 1000
});
nearbySearchController.includedTypes = ['restaurant'];

Родительский компонент <gmp-place-search> автоматически инициирует новый поиск, как только будут заданы необходимые свойства его контроллера.

  • При текстовом поиске он выполняется в тот момент, когда вы присваиваете значение textQuery.
  • Поиск поблизости выполняется после того, как будет указано допустимое значение locationRestriction.

Как реализовать базовый элемент автозаполнения мест

Разработчикам, которым нужен поиск без интерфейса, предоставляемого элементом Place Search, доступен элемент Basic Place Autocomplete.

Этот элемент идеально подходит для создания поля ввода поискового запроса, позволяя полностью контролировать отображение результатов в пользовательском интерфейсе. Единственная задача элемента Autocomplete – предоставлять подсказки мест по мере ввода текста пользователем и программно предоставлять идентификатор выбранного места.

Оно не показывает никаких сведений и не предоставляет информацию, доступную программно.

Текущая реализация

Существующая логика, скорее всего, включает:

  • Отображение на странице поля ввода текста, которое вызывает автозаполнение мест по мере ввода пользователем и показывает результаты.
  • Использование идентификатора места, выбранного пользователем, для получения дополнительных сведений, например с помощью API информации о местах.
  • Показ сведений о выбранном месте.

Перенос на элемент автозаполнения мест

Изменение структуры HTML

Найдите и удалите элемент HTML, к которому прикреплен виджет Autocomplete. Скорее всего, в ней используется стандартное поле ввода HTML.

<input id="pac-input" type="text" placeholder="Search for a location" />

Пример нового HTML-кода, в котором для инициализации базового элемента автозаполнения мест на странице используется веб-компонент.

<gmp-basic-place-autocomplete></gmp-basic-place-autocomplete>

Адаптация логики JavaScript

Логика JavaScript, скорее всего, включает создание виджета Autocomplete, прикрепленного к элементу HTML input. Затем виджет ожидает событие place_changed, которое запускает действие с возвращенными данными.

Пример кода JavaScript, который нужно удалить:

// Get the input element
const input = document.getElementById("pac-input");

// Create the Autocomplete widget instance
const autocomplete = new google.maps.places.Autocomplete(input, {
  fields: ["place_id", "geometry", "name"]
});

// Add a listener for the 'place_changed' event
autocomplete.addListener("place_changed", () => {
  // Your logic to get and display place information
  console.log(place.place_id);
});

Новая логика JavaScript будет получать ссылку на элемент Basic Place Autocomplete и прослушивать события gmp-select:

const placeAutocomplete = document.querySelector('gmp-basic-place-autocomplete');

placeAutocomplete.addEventListener('gmp-select', (event) => {
  console.log(event.place);
});

При выборе места в раскрывающемся списке автозаполнения запускается событие gmp-select. Идентификатор выбранного места можно получить из объекта event. Затем идентификатор места можно использовать для инициализации экземпляра элемента Place Details, чтобы показать информацию о выбранном месте.

Настройка псевдонима

Настройка элемента информации о местах

Ориентация

Элемент информации о местах можно отображать как в горизонтальной, так и в вертикальной ориентации. Используйте атрибут orientation в gmp-place-details-compact, чтобы выбрать вертикальную или горизонтальную ориентацию. Пример:

<gmp-place-details-compact orientation="vertical">

Выберите поля для отображения

Используйте элементы контента, чтобы указать, какой контент должен отображаться в элементе сведений о месте. Например, если исключить элемент контента <gmp-place-type>, то элемент информации о местах не будет показывать тип выбранного места. Полный список элементов контента приведен в справочной документации по PlaceContentConfigElement.

Добавление или удаление полей из элемента "информация о местах" не влияет на стоимость его отрисовки на странице.

Настройка стилей CSS

Для настройки цветов и шрифтов элемента доступны пользовательские свойства CSS. Например, чтобы сделать фон элемента зеленым, задайте следующее свойство CSS:

gmp-place-details-compact {
  --gmp-mat-color-surface: green;
}

Подробную информацию вы можете найти в справочной документации по PlaceDetailsCompactElement.

Настройка элемента поиска мест

Ориентация

Элемент поиска мест можно отображать как в горизонтальной, так и в вертикальной ориентации. Используйте атрибут orientation в <gmp-place-search>, чтобы выбрать вертикальную или горизонтальную ориентацию. Пример:

<gmp-place-search orientation="horizontal" selectable>

Выберите поля для отображения

Используйте элементы контента, чтобы указать, что должно отображаться в элементе поиска мест. Элемент <gmp-place-all-content> можно использовать для показа всего контента, а для настройки отображаемого контента можно использовать набор HTML-тегов.

Если включить <gmp-place-address> в <gmp-place-content-config>, будет отображаться только адрес каждого места, например:

<gmp-place-search orientation="horizontal" selectable>
  <gmp-place-content-config>
    <gmp-place-address></gmp-place-address>
  </gmp-place-content-config>
  <gmp-place-text-search-request></gmp-place-text-search-request>
</gmp-place-search>

Базовая настройка элемента автозаполнения мест

Настройка стилей CSS

Для настройки внешнего вида элемента автозаполнения доступны специальные свойства CSS. Например, чтобы задать светло-фиолетовый цвет фона, нужно установить свойство background-color для элемента.

gmp-basic-place-autocomplete {
  background-color: #d993e6;
}

Подробную информацию можно найти в справочной документации по BasicPlaceAutocompleteElement.

Как обрабатывать события и данные

Элементы Places UI Kit – это интерактивные компоненты, которые позволяют прослушивать события и получать данные программным путем.

Как отслеживать события

Вы можете добавить к элементам прослушиватели событий, чтобы запускать действия в зависимости от взаимодействия с пользователем или состояния элемента.

Событие выбора

  • gmp-select – это событие активируется, когда пользователь делает выбор.
    • В элементе поиска мест оно активируется, когда пользователь нажимает на место в списке результатов.
    • В элементе Basic Place Autocomplete оно срабатывает, когда пользователь нажимает на подсказку в раскрывающемся списке.

Общие события

Элементы поиска мест, информации о местах и базового автозаполнения мест поддерживают следующие события:

  • gmp-load – срабатывает, когда элемент и его контент загружены и отрисованы.
  • gmp-requesterror – срабатывает, когда запрос к серверу не выполняется, например из-за недопустимого ключа API.

Как получить программный доступ к данным элементов

Вы можете программно извлекать определенные данные из элементов после того, как с ними было выполнено взаимодействие или они были загружены.

  • Для элементов поиска мест и информации о местах можно получить следующую информацию:
    • Идентификатор места
    • Местоположение (широта и долгота)
    • Область просмотра
  • Для базового элемента автозаполнения мест можно получить следующую информацию:
    • Идентификатор места

Все остальные данные, содержащиеся в элементах, недоступны для программного доступа.

Более подробные примеры можно найти в документации по элементам поиска мест, информации о местах и автозаполнения мест.

Тестирование и доработка

После интеграции элементов Places UI Kit важно провести тестирование, чтобы обеспечить плавный переход и удобство для пользователей. Тестирование должно охватывать несколько ключевых областей, включая все реализованные вами элементы: информация о местах, поиск мест и базовое автозаполнение мест.

Элемент информации о местах

Для элемента Place Details Element сначала убедитесь, что информация о местах правильно отображается для разных мест. Протестируйте, передавая различные идентификаторы мест в свойство .place элемента <gmp-place-details-place-request>. Используйте идентификаторы, представляющие разные типы заведений (компании с наглядными данными, достопримечательности, основные адреса) и места в разных регионах или на разных языках. Обратите особое внимание на форматирование, макет и наличие контента.

Элемент поиска мест

Если вы реализовали элемент поиска мест, проверьте его отображение и поведение в различных сценариях поиска.

  • Для текстового поиска задайте свойство textQuery элемента <gmp-place-text-search-request> с различными входными данными: общими запросами, конкретными адресами и запросами с приоритетом местоположения.
  • Для Nearby Search задайте свойства locationRestriction и includedTypes в элементе <gmp-place-nearby-search-request>. Используйте фильтры по размеру и типу местоположения.

Убедитесь, что в списке появляются подходящие результаты и что при выборе одного из них корректно активируется событие gmp-select.

Базовый элемент автозаполнения мест

При тестировании базового элемента автозаполнения мест сосредоточьтесь на взаимодействии с пользователем и данных, передаваемых событием выбора. Убедитесь, что событие gmp-select надежно срабатывает, когда пользователь нажимает на подсказку. Убедитесь, что объект event.place в обработчике событий содержит действительный идентификатор места.

Самое главное – протестируйте весь процесс: выберите место в раскрывающемся списке автозаполнения и убедитесь, что его идентификатор места можно использовать для заполнения другого элемента, например элемента сведений о месте.

Обработка ошибок

Тщательное тестирование обработки ошибок необходимо для всех компонентов. Смоделируйте передачу недопустимых или несуществующих идентификаторов мест в элемент информации о местах или использование недопустимых параметров поиска для элемента поиска мест. Вызовите событие gmp-requesterror, сымитировав проблемы с сетью или используя недействительный ключ API, чтобы убедиться, что ваше приложение корректно обрабатывает его. Реализуйте удобные сообщения об ошибках и ведение журналов, чтобы избежать сбоев и путаницы в интерфейсе.