Эта страница переведена с помощью Cloud Translation API.

Внедрение Places UI Kit для существующих пользователей API Places

Цель : заменить реализацию API Places или класса Places на комплект пользовательского интерфейса Places .

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

Разработчики, которые:

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

Предпосылки

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

Загрузка API JavaScript для обновления карт

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

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

Реализуйте элемент «Сведения о месте»

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

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

Вызов Place Details выполняется с помощью HTTP-запроса или с помощью JavaScript API Place Class.
Вы анализируете ответ API и отображаете сведения о месте с помощью HTML и CSS.

Миграция в элемент сведений о месте

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

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

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

Компактный элемент деталей места
Элемент сведений о месте

Дополнительную информацию о том, какой из них использовать, см. в разделе Элемент сведений о месте .

Ваш существующий 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> .
Передайте идентификатор места или объект места свойству места в элементе <gmp-place-details-place-request> .

Ниже приведен пример реализации набора пользовательского интерфейса Place Details в вашей логике JavaScript. Получите ссылку на элемент Place Details. Если он существует, получите ссылку на элемент Place Details Place Request и задайте свойство Place, используя идентификатор Place. В приведенном выше примере HTML-кода стиль элемента Place Details установлен на 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-запроса или использовать класс JavaScript API Place.
С помощью 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

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

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

Он не отображает никаких подробностей и не предоставляет никакой другой программно доступной информации.

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

Ваша существующая логика, вероятно, включает в себя:

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

Миграция для размещения элемента автозаполнения

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

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

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

Пример нового HTML-кода, использующего подход веб-компонентов для инициализации элемента Basic Place Autocomplete на вашей странице.

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

Адаптировать логику JavaScript

Логика вашего JavaScript, вероятно, предполагает создание виджета автодополнения, прикреплённого к 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 и будет прослушивать события 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">

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

Используйте элементы контента для указания контента, который будет отображаться в элементе Place Details. Например, исключение элемента контента <gmp-place-type> остановит отображение типа места выбранного места элементом Place Details. Полный список элементов контента см. в справочной документации 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>

Настройка базового элемента автозаполнения Place

Установить стили CSS

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

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

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

Обработка событий и данных

Элементы набора пользовательского интерфейса Places — это интерактивные компоненты, позволяющие прослушивать события и извлекать данные программным способом.

Следите за событиями

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

Отборочное мероприятие

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

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

Элементы «Поиск места», «Сведения о месте» и «Базовое автозаполнение места» поддерживают следующие события:

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

Программный доступ к данным элемента

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

Для элемента поиска места и элемента сведений о месте вы можете получить следующую информацию:
- Идентификатор места
- Местоположение (широта и долгота)
- Видовой порт
Для элемента автозаполнения Basic Place вы можете получить следующую информацию:
- Идентификатор места

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

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

После интеграции элементов Places UI Kit тестирование имеет решающее значение для плавного перехода и положительного пользовательского опыта. Тестирование должно охватывать несколько ключевых областей, включая все реализованные элементы: элементы Place Details, Place Search и Basic Place Autocomplete.

Элемент сведений о месте

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

Место поиска элемента

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

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

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

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

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

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

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

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

Внедрение Places UI Kit для существующих пользователей API Places Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

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

Предпосылки

Загрузка API JavaScript для обновления карт

Реализуйте элемент «Сведения о месте»

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

Миграция в элемент сведений о месте

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

Адаптировать логику JavaScript

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

Новая логика

Реализовать элемент поиска места

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

Миграция в элемент поиска места

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

Пример поиска поблизости

Пример текстового поиска

Адаптировать логику JavaScript

Реализовать базовый элемент автодополнения Place

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

Миграция для размещения элемента автозаполнения

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

Адаптировать логику JavaScript

Настройка ручки

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

Ориентация

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

Установить стили CSS

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

Ориентация

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

Настройка базового элемента автозаполнения Place

Установить стили CSS

Обработка событий и данных

Следите за событиями

Отборочное мероприятие

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

Программный доступ к данным элемента

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

Внедрение Places UI Kit для существующих пользователей API Places