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

使用 Places UI Kit 建構互動式店家搜尋器

目標

本文將逐步說明如何使用 Google 地圖平台，具體來說是 Maps JavaScript API 和 Places UI Kit：Place Details 元素，開發互動式商家搜尋器應用程式。您將瞭解如何建立顯示商店位置的地圖、動態更新可見商店清單，以及顯示每間商店的豐富地點資訊。

必要條件

建議您熟悉下列項目：

Maps JavaScript API：用於在頁面上顯示地圖，以及匯入 Places UI Kit。
進階標記：用於在地圖上顯示標記。
Places UI Kit：用於在 UI 中顯示商店相關資訊。

在專案中啟用 Maps JavaScript API 和 Places UI Kit。

請先確認您已載入 Maps JavaScript API，並匯入進階標記和Places UI Kit 所需的程式庫，再開始操作。本文件也假設您具備網頁開發知識，包括 HTML、CSS 和 JavaScript。

初始設定

第一步是將地圖加入網頁。這張地圖會用來顯示與商店地點相關的圖釘。

有兩種方法可在頁面中加入地圖：

使用 gmp-map HTML 網頁元件
使用 JavaScript

請選擇最適合您用途的方法。本指南適用於實作地圖的兩種方法。

示範

這個示範影片顯示商店搜尋工具的實際運作情形，顯示灣區的 Google 辦公室位置。系統會為每個地點顯示 Place Details 元素，以及一些屬性範例。

載入及顯示門市位置

在本節中，我們會載入商店資料並在地圖上顯示。本指南假設你已建立現有商店的資訊存放區，可用於提取資訊。商店資料可以來自多種來源，例如資料庫。在這個範例中，我們假設本機 JSON 檔案 (stores.json) 包含商店物件陣列，每個物件代表一個商店位置。每個物件至少應包含 name、location (含 lat 和 lng) 和 place_id。

如果您還沒有商店地點的地點 ID，可以透過多種方式擷取。詳情請參閱 Place ID 說明文件。

stores.json 檔案中的商店詳細資料項目範例如下所示。其中包含「名稱」、「位置 (經緯度)」和「地點 ID」欄位。有個物件可用於儲存商店營業時間 (已截斷)。另外還有兩個布林值，可協助描述商店位置的客製化功能。

{
  "name": "Example Store Alpha",
  "location": { "lat": 51.51, "lng": -0.12 },
  "place_id": "YOUR_STORE_PLACE_ID",
  "opening_hours": { "Monday": "09:00 - 17:00", "...": "..." },
  "new_store_design": true,
  "indoor_seating": false
}

在 JavaScript 程式碼中擷取商店位置資料，並在地圖上為每個商店顯示圖釘。

以下是這項操作的示例。這個函式會接收包含商店詳細資料的物件，並根據每個商店的位置建立標記。

function displayInitialMarkers(storeLocations) {
    if (!AdvancedMarkerElement || !LatLng || !mapElement) return;
    storeLocations.forEach(store => {
        if (store.location) {
            const marker = new AdvancedMarkerElement({
                position: new LatLng(store.location.lat, store.location.lng),
                title: store.name
            });
            mapElement.appendChild(marker);
        }
    });
}

載入商店並在地圖上顯示代表商店位置的圖釘後，請使用 HTML 和 CSS 建立側欄，用來顯示個別商店的詳細資料。

以下是商店定位工具在這個階段的樣貌：

監聽地圖可視區域變更

為提升效能和使用者體驗，請更新應用程式，只在對應位置位於可視地圖區域 (可視區域) 內時，才在側欄中顯示標記和詳細資料。這包括監聽地圖檢視區變更、取消這些事件的觸發，然後只重新繪製必要的標記。

將事件監聽器附加至地圖的閒置事件。這個事件會在所有捲動或縮放作業完成後觸發，為您的計算提供穩定的檢視區。

map.addListener('idle', debounce(updateMarkersInView, 300));

上述程式碼片段會監聽 idle 事件，並呼叫 debounce 函式。使用去抖動函式可確保標記更新邏輯僅在使用者停止與地圖互動一段時間後才執行，進而提升效能。

function debounce(func, delay) {
    let timeoutId;
    return function(...args) {
        const context = this;
        clearTimeout(timeoutId);
        timeoutId = setTimeout(() => {
            func.apply(context, args);
        }, delay);
    };
}

上述程式碼為去抖函式範例。它會採用函式和延遲引數，這些引數可在空白事件監聽器中傳遞。300 毫秒的延遲時間足以等待地圖停止移動，且不會對 UI 造成明顯的延遲。逾時期限一到，系統就會呼叫傳遞的函式，在本例中為 updateMarkersInView。

updateMarkersInView 函式應執行下列動作：

清除地圖上的所有現有標記

檢查商店的位置是否位於目前地圖邊界內，例如：

if (map.getBounds().contains(storeLatLng)) {
  // logic
}

在上述 if 陳述式中，如果商店位置位於地圖檢視區內，請編寫程式碼來顯示標記和商店詳細資料。

使用 Place Details 元素顯示豐富的地點詳細資料

在此階段，應用程式會顯示所有商店位置，使用者可以根據地圖檢視區篩選這些位置。為進一步強化這項功能，我們使用 Place Details 元素新增各商店的詳細資料，例如相片、評論和無障礙資訊。這個範例特別使用Place Details Compact 元素。

資料來源中的每個商店位置都必須有對應的地點 ID。這個 ID 可用來在 Google 地圖上唯一識別位置，也是擷取詳細資料的必要條件。您通常會事先取得這些 Place ID，並將這些 ID 儲存至每個商店記錄。

在應用程式中整合 Place Details Compact 元素

如果系統判斷商店位於目前地圖檢視區內，且正在側欄中顯示，您可以為商店動態建立並插入「地點詳細資料」精簡元素。

針對目前正在處理的商店，從資料中擷取地點 ID。Place ID 用於控制元素要顯示的位置。

在 JavaScript 中，動態建立 PlaceDetailsCompactElement 的例項。系統也會建立新的 PlaceDetailsPlaceRequestElement，將地點 ID 傳遞給該 PlaceDetailsPlaceRequestElement，並附加至 PlaceDetailsCompactElement。最後，使用 PlaceContentConfigElement 設定元素要顯示的內容。

下列函式假設已匯入必要的 Place UI Kit 程式庫，且可在呼叫此函式的範圍內使用，且傳遞至函式的 storeData 包含 place_id。

這個函式會傳回元素，而呼叫程式碼則會負責將元素附加至 DOM。

function createPlaceDetailsCompactElement(storeData) {
    // Create the main details component
    const detailsCompact = new PlaceDetailsCompactElement();
    detailsCompact.setAttribute('orientation', 'vertical'); // Or 'horizontal'

    // Specify the Place ID
    const placeRequest = new PlaceDetailsPlaceRequestElement();
    placeRequest.place = storeData.place_id;
    detailsCompact.appendChild(placeRequest);

    // Configure which content elements to display
    const contentConfig = new PlaceContentConfigElement();
    // For this example, we'll render media, rating, accessibility, and attribution:
    contentConfig.appendChild(new PlaceMediaElement({ lightboxPreferred: true }));
    contentConfig.appendChild(new PlaceRatingElement());
    contentConfig.appendChild(new PlaceAccessibleEntranceIconElement());
    // Configure attribution
    const placeAttribution = new PlaceAttributionElement();
    placeAttribution.setAttribute('light-scheme-color', 'gray');
    placeAttribution.setAttribute('dark-scheme-color', 'gray');
    contentConfig.appendChild(placeAttribution);
    detailsCompact.appendChild(contentConfig);
    // Return the element
    return detailsCompact;
}

在上方範例程式碼中，元素已設定為顯示地點相片、評論評分和無障礙資訊。如要自訂這項設定，請新增或移除其他可用的內容元素。如需查看所有可用選項，請參閱 PlaceContentConfigElement 說明文件。

Place Details 精簡版元素支援透過 CSS 自訂屬性設定樣式。這樣一來，您就能依據應用程式的設計，自訂外觀 (顏色、字型等)。在 CSS 檔案中套用這些自訂屬性。如要瞭解支援的 CSS 屬性，請參閱 PlaceDetailsCompactElement 的參考說明文件。

以下是應用程式在這個階段的示例：

改善商店搜尋工具

您已為商店資訊應用程式奠定穩固基礎。接著，請考慮幾種方法來擴充功能，並打造更豐富、以使用者為中心的體驗。

新增自動完成

將搜尋輸入內容與 Place Autocomplete 整合，改善使用者尋找商店所在區域的方式。當使用者輸入地址、社區或搜尋點，並選取建議內容時，請將地圖設定為自動以該位置為中心，觸發更新附近商店的動作。方法是新增輸入欄位，並附加 Place Autocomplete 功能。選取建議後，地圖會以該點為中心。請記得將其設定為偏向或限制結果的作業區域。

偵測位置

實作偵測使用者目前地理位置的功能，為使用者提供即時相關內容，特別是行動使用者。取得瀏覽器偵測位置存取權後，系統會自動將地圖置中至使用者的位置，並顯示最近的商店。使用者在尋找立即可用的選項時，會非常重視這項「附近」功能。新增按鈕或初始提示，要求位置存取權。

顯示距離和路線

使用者找到感興趣的商店後，只要整合 Routes API，就能大幅提升使用者體驗。針對您列出的每間商店，計算並顯示距離使用者目前所在位置或搜尋地點的距離。此外，請提供使用 Routes API 的按鈕或連結，以便產生從使用者所在位置前往所選商店的路線。接著，您可以將這條路線顯示在地圖上，或連結至 Google 地圖進行導航，讓使用者在找到商店後，能順利前往目的地。

實作這些擴充功能後，您就能使用 Google 地圖平台的更多功能，打造更全面且方便的店面定位工具，直接滿足一般使用者的需求。

結論

本指南已示範建構互動式商店搜尋器的核心步驟。您已瞭解如何使用 Maps JavaScript API 在地圖上顯示自己的商店位置、根據檢視區變更動態更新可見的商店，以及如何根據 Places UI Kit 顯示自己的商店資料。您可以使用現有的商店資訊 (包括 Place ID) 搭配 Place Details 元素，為每個商店提供豐富且標準化的詳細資料，為方便使用者的商店搜尋器建立穩固的基礎。

試試 Maps JavaScript API 和 Places UI Kit，提供功能強大的元件式工具，快速開發精密的位置資訊應用程式。結合這些功能，您就能為使用者打造引人入勝且富含資訊的體驗。

貢獻者

Henrik Valve | DevX 工程師

使用 Places UI Kit 建構互動式店家搜尋器 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

目標