Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

面向现有 Places API 用户采用 Places UI Kit

了解如何将现有 Places API 或 Place Class 实现迁移到 Places UI Kit 组件。

本指南的适用对象

本指南适用于已使用 Places API 实现现有功能，并希望更新代码以使用 Places UI Kit 的开发者。如果您已执行以下操作，本指南将对您最有帮助：

向 Places API（新版或旧版）端点发出 HTTP 请求。
在 Maps JavaScript API 中使用 Place 类。
处理 API 响应，以在 Web 应用的界面中呈现地点信息。

前提条件

在 Google Cloud 项目上启用 Places UI Kit。您可以继续使用现有的 API 密钥，也可以为 Places UI Kit 生成新的 API 密钥。如需了解详情（包括如何限制密钥），请参阅使用 API 密钥。

更新 Maps JavaScript API 加载

Places UI Kit 需要使用动态库导入方法加载 Maps JavaScript API。如果您使用的是直接脚本加载标记，则必须更新此标记。

更新 Maps JavaScript API 的加载脚本后，导入使用 Places UI Kit 所需的库。

实现“地点详情”元素

“地点详情 ”元素和“地点详情（紧凑型） ”元素是用于呈现地点详情的 HTML 元素。

当前实现方式

您可以使用 HTTP 请求执行“地点详情”调用，也可以使用 JavaScript API Place 类。
您需要解析 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 逻辑

现有逻辑

您现有的逻辑可能涉及：

检索地点 ID。
使用 PlacesService().getDetails() 或进行 Web 服务调用。
指定字段数组（对于 JS API）或 FieldMask（对于 Web 服务）以请求特定数据。
在回调解析中，手动选择 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);
}

新逻辑

您的新逻辑将涉及：

检索地点 ID 或地点对象。
获取对 <gmp-place-details-place-request> 元素的引用。
将地点 ID 或地点对象传递给 <gmp-place-details-place-request> 元素上的 place 属性。

以下示例展示了如何在 JavaScript 逻辑中实现“地点详情”UI Kit。获取对“地点详情”元素的引用。如果此元素存在，请获取对“地点详情”地点请求元素的引用，并使用地点 ID 设置 place 属性。在上面的示例 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 请求执行文本搜索或附近搜索，也可以使用 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 后，搜索会运行。

实现基本“地点自动补全”元素

对于需要搜索体验但不需要“地点搜索”元素提供的界面的开发者，可以使用基本“地点自动补全”元素。

此元素非常适合创建搜索输入字段，同时完全控制结果在自定义界面中的显示方式。“自动补全”元素的唯一职责是在用户输入内容时提供地点预测，并以编程方式公开所选地点的地点 ID。

它本身不会显示任何详情，也不会提供任何其他可通过编程方式访问的信息。

当前实现方式

您现有的逻辑可能涉及：

在页面上呈现文本输入字段，该字段会在用户输入内容时调用“地点自动补全”并显示结果。
使用用户所选地点的地点 ID 来提取更多详情，例如使用“地点详情”API。
显示所选地点的详情。

迁移到“地点自动补全”元素

修改 HTML 结构

找到并移除您将“自动补全”widget 附加到的 HTML 元素。它可能使用的是标准 HTML 输入字段。

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

以下是新的 HTML 示例，其中使用 Web 组件方法在页面上初始化基本“地点自动补全”元素。

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

调整 JavaScript 逻辑

您的 JavaScript 逻辑可能涉及创建附加到 input HTML 元素的“自动补全”widget。然后，此 widget 会监听 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 逻辑将获取对基本“地点自动补全”元素的引用，并监听 gmp-select 事件：

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

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

在“自动补全”下拉列表中选择地点后，系统会触发 gmp-select 事件。您可以从 event 对象中检索所选地点的地点 ID。然后，您可以使用该地点 ID 初始化地点详情元素的实例，以显示所选地点的详情。

处理自定义

“地点详情”元素自定义

屏幕方向

“地点详情”元素可以横向和纵向呈现。对 gmp-place-details-compact 使用 orientation 属性，以在纵向和横向之间进行选择。例如：

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

选择要呈现的字段

使用内容元素指定要在“地点详情”元素中呈现的内容。例如，排除内容元素 <gmp-place-type> 会阻止“地点详情”元素呈现所选地点的地点类型。如需查看内容元素的完整列表，请参阅 PlaceContentConfigElement 参考文档。

在“地点详情”元素中添加或移除字段不会改变在页面上呈现元素的费用。

设置 CSS 样式

您可以使用自定义 CSS 属性配置元素的颜色和字体。例如，如需将元素背景设置为绿色，请设置以下 CSS 属性：

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

如需了解详情，请参阅 PlaceDetailsCompactElement 的参考文档。

“地点搜索”元素自定义

屏幕方向

“地点搜索”元素可以横向和纵向呈现。对 <gmp-place-search> 使用 orientation 属性，以在纵向和横向之间进行选择。例如：

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

选择要呈现的字段

使用内容元素指定要在“地点搜索”元素中呈现的内容。您可以使用元素 <gmp-place-all-content> 显示所有内容，也可以使用一系列 HTML 标记来配置呈现的内容。

在 <gmp-place-content-config> 中添加 <gmp-place-address> 将仅呈现每个地点的地址，例如：

<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：当用户进行选择时，系统会触发此事件。
- 在“地点搜索”元素中，当用户点击结果列表中的地点时，系统会触发此事件。
- 在基本“地点自动补全”元素中，当用户点击下拉列表中的预测时，系统会触发此事件。

常见事件

“地点搜索”“地点详情”和基本“地点自动补全”元素均支持以下事件：

gmp-load：当元素及其内容加载和呈现完毕后，系统会触发此事件。
gmp-requesterror：当对服务器的请求失败时（例如，由于 API 密钥无效），系统会触发此事件。

以编程方式访问元素数据

在元素经过互动或加载后，您可以以编程方式从元素中检索特定数据。

对于“地点搜索”元素和“地点详情”元素，您可以检索以下信息：
- 地点 ID
- 位置（纬度和经度）
- 视口
对于基本“地点自动补全”元素，您可以检索以下信息：
- 地点 ID

元素中包含的所有其他数据都无法通过编程方式访问。

如需查看更详细的示例，请参阅“地点搜索”元素、“地点详情”元素、和基本“地点自动补全”元素的单独文档。

集成 Places UI Kit 元素后，测试对于顺利过渡和打造良好的用户体验至关重要。您的测试应涵盖几个关键领域，并解决您实现的所有元素：地点详情、地点搜索和基本“地点自动补全”元素。

“地点详情”元素

对于“地点详情”元素，首先要验证是否针对各种地点正确显示了详情。通过将各种地点 ID 传递给 .place 元素的 <gmp-place-details-place-request> 属性进行测试。使用代表不同商家类型（包含丰富数据的商家、地图注点、基本地址）以及不同区域或语言的地点的 ID。密切关注内容的格式、布局和呈现。

“地点搜索”元素

如果您实现了“地点搜索”元素，请验证其在不同搜索场景下的呈现和行为。

对于文本搜索，请通过使用各种输入（广泛查询、特定地址和包含位置偏差的查询）在 <gmp-place-text-search-request>元素上设置textQuery属性进行测试。
对于附近搜索，请通过在 <gmp-place-nearby-search-request> 元素上设置 locationRestriction 和 includedTypes 属性进行测试。使用不同的位置大小和类型过滤器。

确认列表填充了相关结果，并且在选择时正确触发了 gmp-select 事件。

基本“地点自动补全”元素

对于基本“地点自动补全”元素，请将测试重点放在用户互动和选择事件传递的数据上。确认当用户点击预测时，系统会可靠地触发 gmp-select 事件。验证事件处理脚本中的 event.place 对象是否包含有效的地点 ID。

最重要的是，测试端到端流程：从“自动补全”下拉列表中选择一个地点，并验证其地点 ID 是否可以成功用于填充另一个元素，例如“地点详情”元素。

错误处理

对所有组件进行严格的错误处理测试至关重要。模拟将无效或不存在的地点 ID 传递给“地点详情”元素，或为“地点搜索”元素使用无效的搜索参数。通过模拟网络问题或使用无效的 API 密钥触发 gmp-requesterror 事件，确保您的应用能够妥善处理该事件。实现用户友好的错误消息和日志记录，以防止界面损坏或令人困惑。

面向现有 Places API 用户采用 Places UI Kit 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

本指南的适用对象

前提条件

更新 Maps JavaScript API 加载

实现“地点详情”元素

当前实现方式

迁移到“地点详情”元素

修改 HTML 结构

调整 JavaScript 逻辑

现有逻辑

新逻辑

实现“地点搜索”元素

当前实现方式

迁移到“地点搜索”元素

修改 HTML 结构

附近搜索示例

文本搜索示例

调整 JavaScript 逻辑

实现基本“地点自动补全”元素

当前实现方式

迁移到“地点自动补全”元素

修改 HTML 结构

调整 JavaScript 逻辑

处理自定义

“地点详情”元素自定义

屏幕方向

选择要呈现的字段

设置 CSS 样式

“地点搜索”元素自定义

屏幕方向

选择要呈现的字段

基本“地点自动补全”元素自定义

设置 CSS 样式

处理事件和数据

监听事件

选择事件

常见事件

以编程方式访问元素数据

测试和优化

面向现有 Places API 用户采用 Places UI Kit