為現有 Places API 使用者採用 Places UI Kit

目標：將 Places API 或 Place 類別的實作項目替換為 Places UI Kit。

本指南適用對象

開發人員必須符合以下條件：

  • 向 Places API (新版或舊版) 端點發出 HTTP 要求。
  • 在 Maps JavaScript API 中使用 Place 類別。
  • 處理 API 回應，在網頁應用程式的 UI 中呈現地點資訊。

必要條件

在 Google Cloud 專案中啟用 Places UI Kit。您可以繼續使用現有的 API 金鑰，或為 Places UI Kit 產生新的金鑰。詳情請參閱「使用 API 金鑰」，包括限制金鑰。

更新 Maps JavaScript API 載入作業

Places UI Kit 需要使用 Dynamic Library Import 方法載入 Maps JavaScript API。如果您使用的是直接指令碼載入標記，則必須更新此標記。

更新 Maps JavaScript API 的載入指令碼後，請匯入必要的程式庫，以便使用 Places UI Kit。

實作 Place Details 元素

目前實作

  • 您可以使用 HTTP 要求執行 Place Details 呼叫，或使用 JavaScript API Place 類別。
  • 您會剖析 API 回應，並使用 HTML 和 CSS 顯示地點詳細資料。

遷移至 PlaceDetails 元素

修改 HTML 結構

找出要轉譯地點詳細資料的 HTML 容器。將自訂 HTML 元素 (div、span 等名稱、地址、相片等) 替換為 Place Details Element html。

有兩個元素可供選擇：

  • Place Details 密集元素
  • PlaceDetails 元素

如要進一步瞭解應使用哪一個元素，請參閱「Place Details 元素」。

現有的 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() 或發出網路服務呼叫。
  • 指定欄位陣列 (適用於 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);
}
新邏輯

新的邏輯包含：

  • 擷取地點 ID 或 Place 物件。
  • 取得 <gmp-place-details-place-request> 元素的參照。
  • 將 Place ID 或 Place 物件傳遞至 <gmp-place-details-place-request> 元素上的 place 屬性。

以下範例說明如何在 JavaScript 邏輯中導入 Place Details UI 套件。取得 PlaceDetails 元素的參照。如果存在此元素，請取得對 Place Details Place Request 元素的參照，然後使用 Place ID 設定地點屬性。在上述 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);
  • 您使用 HTTP 要求執行 Text Search 或 Nearby Search，或使用 JavaScript API Place 類別。
  • 您可以使用 FieldMask 指定查詢參數、位置限制或偏差、類型和要求的欄位。
  • 您需要剖析 API 回應、逐一檢視地點陣列，然後手動建立 HTML 清單項目。

修改 HTML 結構

找出您要轉譯地點清單的 HTML 容器。將自訂 HTML 元素 (div、span 等) 替換為 Place Search Element 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>

地點搜尋元素使用 HTML 標記 <gmp-place-list>。新的 HTML 會如下所示。如要讓使用者能夠點選清單項目，請新增 selectable 屬性。

<gmp-place-list id="myPlaceListComponent" selectable></gmp-place-list>

調整 JavaScript 邏輯

取得 <gmp-place-list> DOM 元素的參照。

文字搜尋功能：使用 configureFromSearchByTextRequest(requestOptions)。

const placeListComp = document.getElementById('myPlaceListComponent');
try {
    await placeListComp.configureFromSearchByTextRequest({
        textQuery: 'restaurants in Sydney',
        // locationRestriction: map.getBounds(), // Optional
        // includedType: 'restaurant' // Optional
    });
} catch (error) {
    console.error('UI Kit Place List (Text Search) Error:', error);
}

如要使用 Nearby Search 功能，請使用 configureFromSearchNearbyRequest(requestOptions)：

const placeListComp = document.getElementById('myPlaceListComponent');
if (placeListComp) {
    try {
        await placeListComp.configureFromSearchNearbyRequest({
            locationRestriction: { circle: { center: { latitude: ..., longitude: ... }, radius: 5000 } },
            includedPrimaryTypes: ['cafe', 'bakery'] // Example
        });
    } catch (error) {
        console.error('UI Kit Place List (Nearby Search) Error:', error);
    }
}

文字或附近搜尋要求完成後，Place Search 元素會自動更新 UI，顯示搜尋結果。

自訂處理

Place Details 元素自訂

方向

地點詳細資料元素可在水平和垂直方向中呈現。使用 gmp-place-details-compact 上的 orientation 屬性，選擇直向或橫向。例如：

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

選擇要算繪的欄位

使用內容元素指定要於地點詳細資料元素中算繪的內容。舉例來說，如果排除內容元素 <gmp-place-type>，就會停止讓 Place Details 元素算繪所選地點的 Place Type。如需完整的內容元素清單，請參閱 PlaceContentConfigElement 參考說明文件。

在 Place Details 元素中新增或移除欄位，不會影響在網頁上算繪元素的成本。

設定 CSS 樣式

您可以使用自訂 CSS 屬性設定元素的顏色和字型。舉例來說，如要將元素背景設為綠色，請設定下列 CSS 屬性：

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

詳情請參閱 PlaceDetailsCompactElement 的參考說明文件。

處理事件和資料

Places UI Kit 元素會公開特定事件，例如 Place Search 元素上的 gmp-placeselect 事件，可在使用者點選地點結果時執行動作。詳情請參閱「Place Search 元素」和「Place Details 元素」說明文件。

透過程式輔助方式與 Place Search 元素和 Place Details 元素互動時，可以要求下列資料：

  • 地點 ID
  • 位置 (緯度和經度)
  • 可視區域

如需相關範例，請參閱 Place 清單元素說明文件。

元素中的所有其他資料皆為唯讀。

測試與精進

整合 Place Details 元素或 Place Search 元素後，請務必進行測試，以便順利轉換並提供良好的使用者體驗。您的測試應涵蓋幾個主要領域，並處理您已實作的兩個元件。

針對「Place Details」元素，請先確認系統是否正確顯示各種地點的詳細資料。這項測試包括使用各種 Place ID 代表不同類型的商家 (含豐富資料、興趣點和基本地址)，以及不同區域或語言 (如有) 中的地點。請仔細留意 PlaceDetailsElement 中的格式、版面配置和預期的 UI 元素。

如果您已導入地點搜尋元素，請在不同搜尋情境下驗證其算繪和行為。請同時測試 configureFromSearchNearbyRequest 和 configureFromSearchByTextRequest 方法 (如適用)。使用各種搜尋輸入內容：廣泛查詢、特定地址、具有不同位置偏好設定或限制的查詢，以及依不同地點類型篩選的搜尋。確認清單中填入的結果是否相關，且結果數量是否適合查詢。檢查每個清單項目的視覺呈現方式。

對於這兩個元件來說，嚴謹測試錯誤處理情境是必要的。模擬將無效或不存在的地點 ID 傳遞至 PlaceDetailsElement.configureFromPlace()。針對 Place Search 元素，請測試無效的搜尋參數、要求期間的網路問題，或可能傳回零個結果的情況。

JavaScript 程式碼必須擷取 Places UI Kit 擲回的錯誤。實作使用者友善的錯誤處理機制，例如顯示資訊性訊息、優雅地隱藏元件，或記錄錯誤，以免 UI 發生故障或造成混淆。