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

目標：使用 Places UI Kit 取代 Places API 或 Place 類別的實作項目。

本指南適用對象

開發人員：

  • 向 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 元素

Place Details 元素和 Place Details Compact 元素是 HTML 元素，可顯示地點的詳細資料。

目前實作方式

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

遷移至地點詳細資料元素

修改 HTML 結構

找出要顯示地點詳細資料的 HTML 容器。將自訂 HTML 元素 (名稱、地址、相片等的 div 和 span) 替換為地點詳細資料元素 HTML。

你可以選擇下列兩種元素：

  • Place Details Compact 元素
  • Place Details 元素

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

現有的 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 或地點物件。
  • 取得 <gmp-place-details-place-request> 元素的參照。
  • 將地點 ID 或地點物件傳遞至 <gmp-place-details-place-request> 元素的地點屬性。

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

修改 HTML 結構

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

Place Search 元素是使用 <gmp-place-search> 元件實作。如要設定搜尋類型，請在其中加入下列其中一個已安插的設定元件：

  • <gmp-place-text-search-request> 即可進行文字搜尋。
  • <gmp-place-nearby-search-request>，進行 Nearby Search。

如要定義結果的顯示方式，可以使用 <gmp-place-all-content> 快速鍵，或提供一組個別的呈現元件。您可以直接在父項元件上設定 selectable (允許點選清單項目) 和 orientation (適用於水平或垂直版面配置) 等重要屬性。

Nearby Search 範例
<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> 元素。

接著，請在這個控制器上設定屬性，定義搜尋內容。必要屬性取決於您執行的搜尋類型。

如果是 Text Search (<gmp-place-text-search-request>)，主要屬性為 textQuery：

const textSearchController = document.querySelector('gmp-place-text-search-request');
textSearchController.textQuery = 'museums in London';

如要進行 Nearby Search (<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 後執行搜尋。

實作基本 Place Autocomplete 元素

如果開發人員需要搜尋體驗，但不需要 Place Search 元素提供的 UI，可以使用基本 Place Autocomplete 元素。

這個元素非常適合用來建立搜尋輸入欄位，同時完全掌控結果在自訂使用者介面中的顯示方式。Autocomplete 元素的唯一責任是提供地點預測結果 (使用者輸入時)，並以程式輔助方式公開所選地點的地點 ID。

不會顯示任何詳細資料，也不會提供任何其他可透過程式輔助存取的資訊。

目前實作方式

現有邏輯可能包含：

  • 在網頁上顯示文字輸入欄位，使用者輸入內容時呼叫 Place Autocomplete，並顯示結果。
  • 使用使用者選取地點的地點 ID 擷取更多詳細資料，例如使用 Place Details API。
  • 顯示所選地點的詳細資料。

遷移至 Place Autocomplete 元素

修改 HTML 結構

找出並移除您附加 Autocomplete 小工具的 HTML 元素。這可能是使用標準 HTML 輸入欄位。

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

以下是新的 HTML 範例，使用網頁元件方法在網頁上初始化「基本地點自動完成」元素。

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

調整 JavaScript 邏輯

您的 JavaScript 邏輯可能涉及建立附加至 input HTML 元素的自動完成小工具。這個小工具接著會監聽 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 邏輯會取得 Basic Place Autocomplete 元素參照，並監聽 gmp-select 事件：

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

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

在「自動完成」下拉式選單中選取地點時，系統會觸發 gmp-select 事件。所選地點的 Place ID 可從 event 物件擷取。接著，您可以使用地點 ID 初始化 Place Details 元素的例項，顯示所選地點的詳細資料。

自訂控點

說明文件。

自訂 Place Details 元素

方向

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

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

選擇要算繪的欄位

使用內容元素指定要在「地點詳細資料」元素中顯示的內容。舉例來說，排除內容元素 <gmp-place-type> 後，Place Details 元素就不會再顯示所選地點的地點類型。如需內容元素的完整清單，請參閱 PlaceContentConfigElement 參考說明文件。

在 Place Details 元素中新增或移除欄位，不會改變網頁上算繪元素的費用。

設定 CSS 樣式

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

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

詳情請參閱參考說明文件： PlaceDetailsCompactElement

自訂 Place Search 元素

方向

地點搜尋元素可採用水平和垂直方向呈現。在 <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>

自訂基本的 Place Autocomplete 元素

設定 CSS 樣式

您可以透過自訂 CSS 屬性，自訂自動完成元素的樣式。舉例來說，如要將背景顏色設為淺紫色，請在元素上設定 background-color 屬性。

gmp-basic-place-autocomplete {
  background-color: #d993e6;
}

詳情請參閱BasicPlaceAutocompleteElement參考說明文件。

處理事件和資料

Places UI Kit 元素是互動式元件，可讓您透過程式輔助方式監聽事件及擷取資料。

監聽事件

您可以將事件監聽器新增至元素，根據使用者互動或元素狀態觸發動作。

選取事件

  • gmp-select：使用者進行選取時會觸發此事件。
    • 在地點搜尋元素中，使用者點選結果清單中的地點時，就會觸發這個事件。
    • 在基本地點自動完成元素中，使用者點選下拉式清單中的預測結果時，系統會觸發事件。

常見事件

Place Search、Place Details 和 Basic Place Autocomplete 元素都支援下列事件：

  • gmp-load：元素及其內容載入並完成算繪時觸發。
  • gmp-requesterror：伺服器要求失敗時觸發，例如 API 金鑰無效。

透過程式輔助方式存取元素資料

與元素互動或載入元素後，您可以透過程式輔助從元素中擷取特定資料。

  • 對於 Place Search 元素和 Place Details 元素，您可以擷取下列資訊：
    • 地點 ID
    • 位置 (緯度和經度)
    • 可視區域
  • 對於基本 Place Autocomplete 元素，您可以擷取下列資訊：
    • 地點 ID

元素內含的所有其他資料都無法透過程式輔助存取。

如需更詳細的範例，請參閱 Place Search 元素、Place Details 元素和基本 Place Autocomplete 元素的個別說明文件。

測試與修正

整合 Places UI Kit 元素後，請務必進行測試，確保轉換過程順利，並提供優質的使用者體驗。測試應涵蓋幾個重要領域，並處理您實作的所有元素：Place Details、Place Search 和 Basic Place Autocomplete 元素。

Place Details 元素

對於地點詳細資料元素，請先驗證各種地點的詳細資料是否正確顯示。如要測試，請將各種地點 ID 傳遞至 <gmp-place-details-place-request> 元素的 .place 屬性。使用代表不同機構類型 (具有豐富資料的商家、景點、基本地址) 和不同區域或語言地點的 ID。請特別留意內容的格式、版面配置和呈現方式。

地點搜尋元素

如果您已導入地點搜尋元素，請在不同搜尋情境下驗證其算繪和行為。

  • 如要測試文字搜尋功能，請在 <gmp-place-text-search-request> 元素上設定 textQuery 屬性，並輸入各種內容：廣泛查詢、特定地址，以及帶有位置偏誤的查詢。
  • 如要測試「搜尋附近」功能，請在 <gmp-place-nearby-search-request> 元素上設定 locationRestriction 和 includedTypes 屬性。使用不同大小的位置和類型篩選器。

確認清單會填入相關結果，且選取後會正確觸發 gmp-select 事件。

基本 Place Autocomplete 元素

如果是基本地點自動完成元素，測試重點應放在使用者互動，以及選取事件傳遞的資料。確認使用者點選預測結果時，gmp-select 事件會穩定觸發。確認事件處理常式中的 event.place 物件含有有效地點 ID。

最重要的是，請測試端對端流程：從 Autocomplete 下拉式選單中選取地點，並確認地點 ID 能順利用於填入其他元素，例如 Place Details 元素。

處理錯誤

在所有元件中，嚴格測試錯誤處理機制至關重要。模擬將無效或不存在的地點 ID 傳遞至 Place Details 元素，或使用 Place Search 元素的無效搜尋參數。模擬網路問題或使用無效的 API 金鑰觸發 gmp-requesterror 事件，確保應用程式能妥善處理。實作簡單易懂的錯誤訊息和記錄，避免使用者介面無法正常運作或令人困惑。