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 Autocomplete 服務預測結果
- Place Autocomplete 範例
- 工作階段符記
- AutocompletionRequest參考資料
- AutocompletePrediction參考資料
擷取自動預測結果 (新版)
新的 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}`
}
- Place Autocomplete Data API
- Place Autocomplete 資料預測範例
- Place Autocomplete 資料工作階段範例
- 工作階段符記
- AutocompleteRequest介面參考資料
- AutocompleteSuggestion類別參考資料
- PlacePrediction類別參考資料
地點自動完成小工具
下表列出 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,
  });
}
- Place Autocomplete Widget (Preview) 說明文件
- Place Autocomplete 小工具範例
- Place Autocomplete 元素範例
- PlaceAutocompleteElement類別參考資料