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

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

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

Для кого предназначен этот путеводитель?

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

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

Предварительные требования

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

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

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

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

Реализуйте элемент "Подробная информация о месте".

Элементы «Подробная информация о месте» и «Компактный элемент подробной информации о месте» — это HTML-элементы, отображающие подробную информацию о месте.

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

Запрос сведений о месте можно выполнить с помощью HTTP-запроса или используя класс Place API на JavaScript.
Вы анализируете ответ 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> .
Передайте идентификатор места (Place ID) или объект места (Place Object) в свойство place элемента <gmp-place-details-place-request> .

Ниже приведён пример того, как можно реализовать UI-комплект «Подробности о месте» в вашей JavaScript-логике. Получите ссылку на элемент «Подробности о месте». Если он существует, получите ссылку на элемент «Запрос на место» в разделе «Подробности о месте» и установите свойство «Место», используя идентификатор места. В приведённом выше примере 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 ID) для выбранного места.

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

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

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

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

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

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

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

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

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

<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 . Затем этот идентификатор можно использовать для инициализации экземпляра элемента «Подробная информация о месте» , чтобы отобразить подробную информацию о выбранном месте.

Обработка настройки

Настройка элемента "Подробная информация о месте"

Ориентация

Элемент «Подробная информация о месте» может отображаться как в горизонтальной, так и в вертикальной ориентации. Используйте атрибут 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 ID) свойству .place элемента ` <gmp-place-details-place-request> `. Используйте идентификаторы, представляющие различные типы предприятий (компании с подробными данными, достопримечательности, простые адреса) и места в разных регионах или на разных языках. Обратите особое внимание на форматирование, макет и наличие контента.

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

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

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

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

Элемент автозаполнения Basic Place

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

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

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

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

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

Для кого предназначен этот путеводитель?

Предварительные требования

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

Реализуйте элемент "Подробная информация о месте".

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

Элемент "Миграция к месту назначения"

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

Адаптируйте логику JavaScript.

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

Новая логика

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

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

Элемент поиска «Миграция на место»

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

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

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

Адаптируйте логику JavaScript.

Реализация базового элемента автозаполнения для размещения объектов.

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

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

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

Адаптируйте логику JavaScript.

Обработка настройки

Настройка элемента "Подробная информация о месте"

Ориентация

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

Задать стили CSS

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

Ориентация

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

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

Задать стили CSS

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

Слушайте новости о событиях

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

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

Доступ к данным элементов программным способом

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

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