本頁面由 Cloud Translation API 翻譯而成。

什麼是 Places UI Kit？如何運用這項工具包建構引人入勝的解決方案？

簡介

對全球數百萬使用者而言，Google 地圖是準確且最新的地點資訊來源。Google 豐富的資料庫包含全球超過 2.5 億個地點，以及使用者評論、相片和評分，可提供無與倫比的詳細資訊和信任度。為提供最新且正確的資料，我們每天會更新地圖 1 億次。

Places UI Kit 是經濟實惠的現成元件程式庫，可提供 Google 地圖中豐富的地點資訊。您可以在選用的地圖上，將 Google 可靠又熟悉的 Places 體驗整合至前端用途。

元件

Places UI Kit 提供一系列個別 UI 元件，可單獨或搭配使用，打造流暢的 Places 體驗。

地點詳細資料：這個元件會顯示地點的詳細資訊，例如名稱、地址、電話號碼、網站、營業時間和使用者評論。
地點搜尋：這個元件會顯示附近地點的清單，可依類別或透過任意文字搜尋。
基本地點自動完成：這個元件會建立文字輸入欄位，並顯示與輸入內容相符的預測地點下拉式清單。

Places UI Kit 的主要優點

操作簡單：您只需編寫少量程式碼，即可在應用程式中導入 Google 值得信賴的地點使用者體驗。
適用於任何地圖：您現在可以在非 Google 地圖上使用地點內容。
熟悉的使用者介面：這些元件提供與 Google 地圖體驗一致的使用者介面，讓使用者操作起來得心應手。
自訂：Places UI Kit 提供多種視覺自訂選項，無須額外付費。您可以使用各種設定和自訂 CSS 屬性來設定顯示元素。
符合成本效益：與直接使用 Places API 相比，Places UI Kit 可能是更符合成本效益的解決方案。

實際應用案例

您可以在各種應用程式中使用 Places UI Kit，提升使用者體驗。

本地探索應用程式：「待辦事項」應用程式可以使用地點搜尋元件，顯示附近的餐廳、咖啡廳或景點清單。使用者從清單中選取地點時，系統會使用「地點詳細資料」元件顯示該地點的詳細資訊。
旅遊規劃應用程式：旅遊應用程式可使用地點搜尋功能，讓使用者搜尋特定城市中的飯店或景點。接著，地點詳細資料元件就會顯示每個地點的相片、評分和評論，協助規劃行程。
房地產和房源搜尋入口網站：房地產應用程式可使用地點搜尋元件，顯示附近不同類別的地點，協助潛在購屋者或租屋者在安排看房前，瞭解該社區的生活型態是否適合自己。
即時通訊和社群媒體應用程式：即時通訊和社群媒體應用程式可使用地點搜尋功能，搜尋及建議附近的地點，協助使用者輕鬆找到聚會地點。使用者分享地點時，可使用 Place Details 元件顯示豐富的地點資訊。使用者可以透過預先建構的 Google 地圖按鈕，在 Google 地圖上輕鬆準確地探索更多地點和旅遊資訊。

自訂

您可以自訂 Places UI Kit 元件的內容豐富度和樣式，以符合自身需求。

舉例來說，您可以透過自訂 CSS 屬性 (例如地點詳細資料元件的 CSS 屬性)，調整元件的外觀和風格，以符合應用程式的設計。你可以自訂顏色、字型和其他視覺元素。進行視覺修改時，請務必遵守歸因規定。舉例來說，您可以使用 --gmp-mat-color-primary CSS 屬性，變更用於連結和評論數的主要顏色。

您可以透過巢狀 gmp-place-content-config 元素選取及設定內容，控制顯示的特定地點內容，也可以直接使用 gmp-place-all-content 顯示所有可用內容。

文件中提供自訂工具，可協助您查看不同樣式設定的視覺效果。

導入指南

無論是單一或多平台的開發人員，都可透過 JavaScript 版 Maps SDK，以及 Android 和 iOS 版 Places SDK 使用 Places UI Kit，

開始使用

如要開始使用 Places UI Kit，請按照下列步驟操作：

設定 Google Cloud 專案：您需要有 Cloud 專案和帳單帳戶，才能使用 Places UI Kit。
啟用 Places UI Kit：您必須為專案啟用 Places UI Kit。
取得 API 金鑰：您必須使用 API 金鑰驗證要求。

如需更多平台專屬詳細資料，請參閱 JavaScript、Android 和 iOS 適用的 Places UI Kit 入門指南。

導入範例

以下範例說明如何使用動態 JavaScript 地圖導入 Place Search 和 Place Details。使用者可以根據任意文字搜尋附近地點。點選搜尋結果清單中的地點時，動態地圖會顯示「地點詳細資料」元件。

程式碼片段如下。您可以在這個 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>

新增 Place Search 元件。Place Search 元件提供水平和垂直版面配置。在本範例中，我們使用橫向版面配置。「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>

接著新增「地點詳細資料」元件，這個元件提供精簡和完整版面配置，且支援直向和橫向。本範例使用精簡的橫向版面配置。與 Place Search 元件類似，我們新增了兩個子項元素：

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 中，匯入這個範例所需的程式庫。Places 程式庫會匯入 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);

將點擊事件監聽器新增至搜尋按鈕，以啟動地點搜尋。搜尋結果載入時，請為每個地點建立標記，並為標記新增點擊監聽器。點選標記後，系統會要求並顯示對應的地點詳細資料。

找到地點並載入 Place Search 元素後，Place Search 元素的「places」屬性會填入結果陣列。每個結果都是地點物件，內含地點 ID、座標和可視區域。如要擷取詳細資料，請將地點 ID 或整個地點物件傳遞至 Place Details 元素。

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 地圖平台解決方案工程師

什麼是 Places UI Kit？如何運用這項工具包建構引人入勝的解決方案？ 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

簡介

元件