什么是 Places UI Kit？如何使用它来构建富有吸引力的解决方案？

简介

对于全球数百万用户而言，Google 地图是获取准确且最新地点信息的首选来源。Google 拥有丰富的数据库，其中包含全球超过 2.5 亿个地点的相关信息，包括用户评价、照片和评分，可提供无与伦比的详细程度和可信度。为了提供最新且真实的数据，我们每天都会对地图进行 1 亿次更新。

Places UI Kit 是一款即用型高性价比组件库，可利用 Google 地图上丰富的地点信息。借助该服务，您可以将 Google 可靠且熟悉的地点体验集成到您选择的地图上的前端使用情形中。

组件

Places UI Kit 提供了一组可单独使用或一起使用的单个界面组件，可用于打造顺畅的地点体验。

  • 地点详情：此组件可呈现有关地点的详细信息，例如名称、地址、电话号码、网站、营业时间和用户评价。

  • 地点搜索：此组件会按类别或通过自由文本搜索显示附近地点的列表。

  • 基本地点自动补全：此组件会创建一个文本输入字段，并显示与输入内容匹配的预测地点下拉列表。

Places UI Kit 组件

Places UI Kit 的主要优势

  • 易用性：只需少量代码，即可将 Google 可信赖的地点用户体验融入您的应用。

  • 可在任何地图上使用：您现在可以首次在非 Google 地图上使用 Places 内容。

  • 熟悉的界面：这些组件提供的界面与 Google 地图体验一致，因此用户可以直观地使用。

  • 自定义：Places 界面套件提供丰富的视觉自定义选项，而且无需额外付费。您可以使用各种设置和自定义 CSS 属性来配置显示元素。

  • 经济实惠：与直接使用 Places API 相比，Places UI Kit 是一种更经济实惠的解决方案。

实际应用场景

Places UI Kit 可用于各种应用，以提升用户体验。

  • 本地发现应用：“活动”应用可以使用地点搜索组件来显示附近的餐厅、咖啡馆或景点列表。当用户从列表中选择某个地点后，您可以使用 Place Details 组件显示有关该地点的更多信息。

  • 旅游规划应用：旅游应用可以使用地点搜索功能，让用户搜索特定城市中的酒店或地图注点。然后，“地点详情”组件可以显示每个地点的照片、评分和评价，以帮助用户规划行程。

  • 房地产和房产搜索门户网站：房地产应用可以使用地点搜索组件来显示不同类别的附近地点，帮助潜在的购房者或租房者在预约看房之前了解社区的生活方式是否适合自己。

  • 即时通讯和社交媒体应用：即时通讯和社交媒体应用可以使用地点搜索功能来搜索和建议附近的地点，帮助用户轻松找到聚会地点。当用户分享地点时，可以使用“地点详情”组件显示丰富的地点信息。借助预建的 Google 地图按钮，用户可以轻松准确地在 Google 地图中探索更多地点和旅行信息。

自定义

Places UI Kit 自定义

您可以根据自己的需求自定义 Places 界面套件组件的内容丰富度和样式。

使用自定义 CSS 属性（例如“地点详情”组件的 CSS 属性）可让您根据应用的设计量身定制组件的外观和风格。您可以自定义颜色、字体和其他视觉方面。在进行视觉修改时，请务必遵守提供方信息要求。例如，您可以使用 --gmp-mat-color-primary CSS 属性更改用于链接和评价数量的主颜色。

您可以使用嵌套的 gmp-place-content-config 元素来选择和配置内容，从而控制所显示的特定地点内容，也可以直接使用 gmp-place-all-content 来显示所有可用的内容。

文档中提供了一个自定义工具，可帮助您直观呈现不同的样式配置。

实施指南

Places UI Kit 可通过 Maps JavaScript 和 Places SDK for Android 及 iOS 获取。

使用入门

如需开始使用 Places UI Kit，您需要按以下步骤操作：

  1. 设置 Google Cloud 项目：您需要一个具有结算账号的 Cloud 项目才能使用 Places 界面套件。

  2. 启用 Places UI Kit：您必须为项目启用 Places UI Kit。

  3. 获取 API 密钥：您需要 API 密钥才能对请求进行身份验证。

如需了解更多特定于平台的详情，请参阅适用于 JavaScript、Android 和 iOS 的 Places 界面套件入门指南。

实现示例

下面是一个使用动态 JavaScript 地图实现地点搜索和地点详情的示例。用户可以根据自由文本搜索附近的地点。点击搜索结果列表中的地点时，地点详情组件将显示在动态地图上。

以下是代码段。您可以在此 GitHub 代码库中找到演示和完整代码。

在开始之前，请确保您已完成与 JavaScript 相关的上述“入门”步骤。

在 HTML 中加载所需的库。

<script>
  (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
    key: "YOUR_API_KEY",
    v: "weekly",
    // Use the 'v' parameter to indicate the version to use (weekly, beta, alpha, etc.).
    // Add other bootstrap parameters as needed, using camel case.
  });
</script>

在 HTML 中，添加地图容器、文本输入字段和搜索按钮。此地图容器将包含在 JavaScript 中创建的动态地图。输入框允许用户输入搜索查询。

<div id="map-container"></div>
<div class="controls">
    <input type="text" class="query-input" />
    <button class="search-button">Search</button>
</div>

添加“地点搜索”组件。“地点搜索”组件提供水平和垂直布局。在此示例中，我们使用横向布局。“selectable”属性可让搜索结果列表项可供点击（点击时会触发 gmp-select 事件）。

在 gmp-place-search 元素中，我们添加了两个子元素：

  • gmp-place-all-content 用于显示所有可用的内容
  • gmp-place-text-search-request 用于配置地点搜索元素。

在此示例中，我们将通过 JavaScript 设置配置

<div class="list-container">
    <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>
</div>

接下来，添加“地点详情”组件，该组件提供紧凑型和完整型布局，每种布局都支持竖屏和横屏方向。此示例使用紧凑型横向布局。与“地点搜索”组件类似，我们添加了两个子元素：

  • gmp-place-all-content 表示显示所有可用的内容
  • gmp-place-details-place-request 用于选择地点。

在此示例中，我们将通过 JavaScript 设置地点

<div id="details-container">
     <gmp-place-details-compact orientation="horizontal">
        <gmp-place-details-place-request></gmp-place-details-place-request> 
        <gmp-place-all-content></gmp-place-all-content>
    </gmp-place-details-compact> 
</div>

在 JavaScript 中，导入本示例所需的库。地点库会导入适用于 JavaScript 的 Places UI Kit 库。

const {Map} = await google.maps.importLibrary("maps");
await google.maps.importLibrary("places");
({AdvancedMarkerElement} = await google.maps.importLibrary("marker"));
({LatLngBounds, LatLng} = await google.maps.importLibrary("core"));

创建动态地图。

const mapContainer = document.getElementById("map-container");
const mapOptions = {
    center: {lat: 37.422, lng: -122.085},
    zoom: 12 
};
const gMap = new Map(mapContainer, mapOptions);

向搜索按钮添加点击监听器，以启动地点搜索。当搜索结果加载时，为每个地点创建标记并为其添加点击监听器。点击标记后，系统会请求并显示相应的地点详情。

当系统找到地点并加载地点搜索元素时，地点搜索元素的 places 属性会填充一个结果数组。每个结果都是一个地点对象，其中包含相应地点的 ID、坐标和视口。如需提取详情，请将地点 ID 或整个地点对象传递给“地点详情”元素。

const queryInput = document.querySelector(".query-input");
const searchButton = document.querySelector(".search-button");
const placeSearch = document.querySelector("gmp-place-search");
const placeSearchQuery = document.querySelector("gmp-place-text-search-request");
const placeDetails = document.querySelector("gmp-place-details-compact");
const placeRequest = document.querySelector("gmp-place-details-place-request");

placeDetailsPopup = new AdvancedMarkerElement({
    map: null,
    content: placeDetails,
    zIndex: 1
});

searchButton.addEventListener("click", searchPlaces);

function searchPlaces(){    
    if (queryInput.value.trim()) {
        placeSearchQuery.textQuery = queryInput.value.trim();
        placeSearchQuery.locationBias = gMap.getBounds();
        placeSearch.addEventListener('gmp-load', addMarkers, { once: true });
    }
}

async function addMarkers(){
    const bounds = new LatLngBounds();
    placeSearch.places.forEach((place) => {
        let marker = new AdvancedMarkerElement({
            map: gMap,
            position: place.location
        });
        bounds.extend(place.location);
        marker.addListener('click',(event) => {
            placeRequest.place = place;
            placeDetails.style.display = 'block';
            placeDetailsPopup.position = place.location;
            placeDetailsPopup.map = gMap;
            gMap.fitBounds(place.viewport, {top: 200, left: 100});
        });
        gMap.setCenter(bounds.getCenter());
        gMap.fitBounds(bounds);
    });
}

请务必查看此 GitHub 代码库中的演示和完整代码。

可帮助您打造

贡献者

主要作者：

Teresa Qin | Google Maps Platform 解决方案工程师