遷移至新版 Place Autocomplete

歐洲經濟區 (EEA) 開發人員

Place Autocomplete 是 Maps JavaScript API Places Library 的功能。您可以使用自動完成功能，在應用程式中提供 Google 地圖搜尋欄位的預先輸入搜尋功能。

本頁面說明舊版和新版 Place Autocomplete 功能的差異。這兩個版本都有兩種一般方式可整合自動完成功能：

自動完成程式輔助介面

下表列出使用程式輔助 Place Autocomplete 時，Place Autocomplete 服務 (舊版) 和 Autocomplete Data API (新版) 的主要差異：

PlacesService (舊版) Place (新)
Place Autocomplete 服務參考資料 自動完成資料 (新) 參考資料
AutocompletionRequest AutocompleteRequest
AutocompleteService.getPlacePredictions AutocompleteSuggestion.fetchAutocompleteSuggestions
AutocompletePrediction PlacePrediction
方法需要使用回呼來處理結果物件和 PlacesServiceStatus 回應。 使用 Promise，並以非同步方式運作。
方法需要進行 PlacesServiceStatus 檢查。 不需要檢查狀態，可使用標準錯誤處理程序。 瞭解詳情。
建立 Autocomplete 執行個體時，地點資料欄位會設為選項。 稍後呼叫 fetchFields() 時，系統會設定地點資料欄位。
支援查詢預測 (僅限 SearchBox)。 查詢預測功能不適用於 Autocomplete 類別。
僅限一組固定的地點類型和地點資料欄位。 存取更多地點類型和地點資料欄位。

舊版和新版 Autocomplete API 都會使用下列項目：

程式碼比較 (程式輔助)

本節會比較自動完成功能的程式碼，說明程式設計介面中 Places Service 與 Place 類別的差異。

擷取自動完成預測結果 (舊版)

舊版 Places Service 可讓您以程式輔助方式擷取自動完成預測結果，與 Autocomplete 類別相比，可更有效地控制使用者介面。在下列範例中，系統會對「par」提出單一要求，並使用 AutocompletionRequest (包含輸入值和一組用於預測偏誤的界限)。這個範例會傳回AutocompletePrediction執行個體清單，並顯示每個執行個體的說明。範例函式也會建立工作階段符記，並套用至要求。

function init() {   const placeInfo = document.getElementById("prediction");   const service = new google.maps.places.AutocompleteService();   const placesService = new google.maps.places.PlacesService(placeInfo);   var sessionToken = new google.maps.places.AutocompleteSessionToken();    // Define request options.   let request = {     input: "par",     sessionToken: sessionToken,     bounds: {       west: -122.44,       north: 37.8,       east: -122.39,       south: 37.78,     },   }    // Display the query string.   const title = document.getElementById("title");   title.appendChild(     document.createTextNode('Place predictions for "' + request.input + '":'),   );    // Perform the query and display the results.   const displaySuggestions = function (predictions, status) {     // Check the status of the Places Service.     if (status != google.maps.places.PlacesServiceStatus.OK || !predictions) {       alert(status);       return;     }      predictions.forEach((prediction) => {       const li = document.createElement("li");       li.appendChild(document.createTextNode(prediction.description));       document.getElementById("results").appendChild(li);     });      const placeRequest = {       placeId: predictions[0].place_id,       fields: ["name", "formatted_address"],     };      placesService.getDetails(placeRequest, (place, status) => {       if (status == google.maps.places.PlacesServiceStatus.OK && place) {         placeInfo.textContent = `           First predicted place: ${place.name} at ${place.formatted_address}`       }     });    };    // Show the results of the query.   service.getPlacePredictions(request, displaySuggestions); }

擷取自動預測結果 (新版)

新的 Place 類別也提供以程式輔助方式擷取自動完成預測的功能，與 PlaceAutocompleteElement 類別相比，可更有效控制使用者介面。在下列範例中，系統會對「par」發出單一要求，並使用 AutocompleteRequest 包含輸入值和一組預測偏誤的界限。這個範例會傳回 placePrediction 執行個體清單，並顯示每個執行個體的說明。範例函式也會建立工作階段符記，並套用至要求。

async function init() {   let sessionToken = new google.maps.places.AutocompleteSessionToken();    // Define request options.   let request = {     input: "par",     sessionToken: sessionToken,     locationBias: {       west: -122.44,       north: 37.8,       east: -122.39,       south: 37.78,     },   };    // Display the query string.   const title = document.getElementById("title");   title.appendChild(     document.createTextNode('Place predictions for "' + request.input + '":'),   );    // Perform the query and display the results.   const { suggestions } =     await google.maps.places.AutocompleteSuggestion.fetchAutocompleteSuggestions(request);    const resultsElement = document.getElementById("results");    for (let suggestion of suggestions) {     const placePrediction = suggestion.placePrediction;     const listItem = document.createElement("li");      listItem.appendChild(       document.createTextNode(placePrediction.text.text),     );      resultsElement.appendChild(listItem);   }    // Show the first predicted place.   let place = suggestions[0].placePrediction.toPlace();    await place.fetchFields({     fields: ["displayName", "formattedAddress"],   });    const placeInfo = document.getElementById("prediction");    placeInfo.textContent = `     First predicted place: ${place.displayName} at ${place.formattedAddress}` }

地點自動完成小工具

下表列出 Places 服務 (舊版) 和 Place 類別 (新版) 之間，使用自動完成小工具的一些主要差異：

地點介面集服務 (舊版) 地點 (新版)
Autocomplete 類別，用於地點預測。 PlaceAutocompleteElement 類別，用於地點預測。
SearchBox 類別，用於查詢預測。
查詢預測功能不適用於 Autocomplete 類別。
只有預設的輸入預留位置文字會本地化。 文字輸入預留位置、預測結果清單標誌和地點預測結果都支援區域本地化。
小工具會使用 setBounds() 或 autocomplete.bindTo() 將搜尋範圍限制 (偏向) 在指定範圍內，並使用 strictBounds 將結果限制在指定範圍內。 小工具會使用 locationBias 屬性，將結果調整為指定範圍，並使用 locationRestriction 屬性，將搜尋範圍限制在指定範圍內。
小工具只能使用標準 HTML 輸入元素整合。 小工具可使用標準 HTML 輸入元素或 gmp-place-autocomplete 元素整合。
使用小工具時，使用者可能會要求無效的內容 (例如「bisneyland」)，因此必須明確處理這種情況。 小工具只會傳回所提供建議的結果，無法針對任意值發出要求，因此不需要處理可能無效的要求。
傳回舊版 PlaceResult 執行個體。 傳回 Place 例項。
地點資料欄位會設為 Autocomplete 物件的選項。 使用者選取地點並呼叫 fetchFields() 時，系統會設定地點資料欄位。
僅限一組固定的地點類型和地點資料欄位。 存取更多地點類型和地點資料欄位。

程式碼比較 (小工具)

本節將比較自動完成功能的程式碼，說明舊版 Place Autocomplete 小工具與新版 Place Autocomplete 元素之間的差異。

Place Autocomplete 小工具 (舊版)

地點服務提供兩種自動完成小工具，您可以使用 Autocomplete 和 SearchBox 類別新增。每種小工具都可以新增至地圖做為地圖控制項，或直接嵌入網頁。以下程式碼範例說明如何將 Autocomplete 小工具嵌入為地圖控制項。

  • Autocomplete 小工具建構函式會採用兩個引數：
    • text 類型的 HTML input 元素。自動完成服務會監控這個輸入欄位，並將結果附加到這裡。
    • 選用的 AutocompleteOptions 引數，可指定其他選項來限制查詢。
  • 如要設定邊界，可以呼叫 autocomplete.bindTo()，將 Autocomplete 例項明確繫結至地圖。
  • 在自動完成選項中指定地點資料欄位。
function initMap() {   const map = new google.maps.Map(document.getElementById("map"), {     center: { lat: 40.749933, lng: -73.98633 },     zoom: 13,     mapTypeControl: false,   });   const card = document.getElementById("pac-card");   const input = document.getElementById("pac-input");   const options = {     fields: ["formatted_address", "geometry", "name"],     strictBounds: false,   };    map.controls[google.maps.ControlPosition.TOP_LEFT].push(card);    const autocomplete = new google.maps.places.Autocomplete(input, options);    // Bind the map's bounds (viewport) property to the autocomplete object,   // so that the autocomplete requests use the current map bounds for the   // bounds option in the request.   autocomplete.bindTo("bounds", map);    const infowindow = new google.maps.InfoWindow();   const infowindowContent = document.getElementById("infowindow-content");    infowindow.setContent(infowindowContent);    const marker = new google.maps.Marker({     map,     anchorPoint: new google.maps.Point(0, -29),   });    autocomplete.addListener("place_changed", () => {     infowindow.close();     marker.setVisible(false);      const place = autocomplete.getPlace();      if (!place.geometry || !place.geometry.location) {       // User entered the name of a Place that was not suggested and       // pressed the Enter key, or the Place Details request failed.       window.alert("No details available for input: '" + place.name + "'");       return;     }      // If the place has a geometry, then present it on a map.     if (place.geometry.viewport) {       map.fitBounds(place.geometry.viewport);     } else {       map.setCenter(place.geometry.location);       map.setZoom(17);     }      marker.setPosition(place.geometry.location);     marker.setVisible(true);     infowindowContent.children["place-name"].textContent = place.name;     infowindowContent.children["place-address"].textContent =       place.formatted_address;     infowindow.open(map, marker);   }); }

Place Autocomplete 小工具 (新版)

Place 類別提供 PlaceAutocompleteElement，這是 HTMLElement 子類別，可提供 UI 元件，新增至地圖做為地圖控制項，或直接嵌入網頁。下列程式碼範例說明如何將 PlaceAutocompleteElement 小工具嵌入為地圖控制項。

Place Autocomplete 小工具包含下列改善項目：

  • Autocomplete 小工具 UI 支援區域本地化 (包括 RTL 語言)，適用於文字輸入預留位置、預測結果清單標誌和地點預測結果。
  • 進階無障礙功能，包括支援螢幕閱讀器和鍵盤互動。
  • Autocomplete 小工具會傳回新的 Place 類別，簡化回傳物件的處理流程。
  • 更有效地支援行動裝置和小螢幕。
  • 更出色的效能，更清楚的圖形外觀。

主要實作差異包括：

  • PlaceAutocompleteElement 會提供自己的輸入欄位，並使用 HTML 或 JavaScript 直接插入網頁 (而不是提供現有的輸入元素)。
  • 查詢預測功能不適用於 Autocomplete 類別。
  • PlaceAutocompleteElement 是使用 PlaceAutocompleteElementOptions 建構而成。
    • 地點資料欄位是在選取時間 (呼叫 fetchFields() 時) 指定。
  • 使用 locationBounds 或 locationRestriction 選項設定邊界。
let map; let marker; let infoWindow;  async function initMap() {   // Request needed libraries.   const [{ Map }, { AdvancedMarkerElement }] = await Promise.all([     google.maps.importLibrary("marker"),     google.maps.importLibrary("places"),   ]);    // Initialize the map.   map = new google.maps.Map(document.getElementById("map"), {     center: { lat: 40.749933, lng: -73.98633 },     zoom: 13,     mapId: "4504f8b37365c3d0",     mapTypeControl: false,   });    const placeAutocomplete =     new google.maps.places.PlaceAutocompleteElement({       locationRestriction: map.getBounds(),     });    placeAutocomplete.id = "place-autocomplete-input";   const card = document.getElementById("place-autocomplete-card");    card.appendChild(placeAutocomplete);   map.controls[google.maps.ControlPosition.TOP_LEFT].push(card);    // Create the marker and infowindow.   marker = new google.maps.marker.AdvancedMarkerElement({     map,   });   infoWindow = new google.maps.InfoWindow({});    // Add the gmp-select listener, and display the results on the map.   placeAutocomplete.addEventListener("gmp-select", async ( place ) => {     const place = event.placePrediction.toPlace();     await place.fetchFields({       fields: ["displayName", "formattedAddress", "location"],     });     // If the place has a geometry, then present it on a map.     if (place.viewport) {       map.fitBounds(place.viewport);     } else {       map.setCenter(place.location);       map.setZoom(17);     }      let content =       '<div id="infowindow-content">' +       '<span id="place-displayname" class="title">' +       place.displayName +       '</span><br />' +       '<span id="place-address">' +       place.formattedAddress +       '</span>' +       '</div>';      updateInfoWindow(content, place.location);     marker.position = place.location;   }); }  // Helper function to create an info window. function updateInfoWindow(content, center) {   infoWindow.setContent(content);   infoWindow.setPosition(center);   infoWindow.open({     map,     anchor: marker,     shouldFocus: false,   }); }