基本 Place Autocomplete 元素

選取平台： Android iOS JavaScript

BasicPlaceAutocompleteElement 會建立文字輸入欄位、在 UI 選單中提供地點預測結果，以及傳回所選地點的地點 ID。

Basic Place Autocomplete 元素比 PlaceAutocompleteElement 更容易導入，且有以下差異：

  • Basic Place Autocomplete 元素會傳回 Place 物件，其中只包含地點 ID，而不是 PlacePrediction 物件。您可以直接使用傳回的地點 ID 和 Places UI Kit Details 元素，取得其他地點詳細資料，而 PlacePrediction 物件則必須先轉換為地點 ID。
  • 基本地點自動完成元素不需要載入 Places API。
  • 使用者選取地點預測結果時，Basic Place Autocomplete 元素會清除輸入欄位。

必要條件

如要使用 Basic Place Autocomplete 元素，請務必在 Google Cloud 專案中啟用 Places UI Kit。詳情請參閱「 開始使用」一文。

新增基本地點自動完成元素

本節說明如何在網頁或地圖中加入基本 Autocomplete 元素。

在網頁中加入基本 Autocomplete 元素

如要在網頁中加入 BasicAutocomplete 元素，請建立新的 google.maps.places.BasicPlaceAutocompleteElement，然後附加至網頁，如以下範例所示：

// Request needed libraries.
const {BasicPlaceAutocompleteElement} = await google.maps.importLibrary('places');
// Create the input HTML element and append it.
const placeAutocomplete = new BasicPlaceAutocompleteElement();
document.body.appendChild(placeAutocomplete);

在地圖中加入基本 Autocomplete 元素

如要在地圖中加入 Basic Autocomplete 元素，請將 BasicPlaceAutocompleteElement 附加至 gmp-map 元素，並使用 slot 屬性設定其位置，如以下範例所示：

<gmp-map zoom="12" center="37.4220656,-122.0840897" map-id="DEMO_MAP_ID">
  <gmp-basic-place-autocomplete
    slot="control-inline-start-block-start"></gmp-basic-place-autocomplete>
</gmp-map>
index.html

限制 Autocomplete 預測結果

根據預設，Basic Place Autocomplete 會顯示所有地點類型 (優先顯示使用者所在位置附近的預測結果)。您可以限制或自訂調整結果，將 BasicPlaceAutocompleteElementOptions 設為顯示更相關的預測結果。

限制結果後，Basic Autocomplete 元素會略過超出限制區域的所有結果。常見做法是將結果限制在地圖範圍內。自訂調整結果會讓 BasicAutocomplete 元素顯示指定區域內的結果，但有些相符項目可能會超出這個區域。

如未提供任何邊界或地圖可視區域，API 就會嘗試根據使用者的 IP 位址偵測所在位置，然後針對該位置調整結果。請盡可能設定邊界，否則不同使用者可能會收到不同的預測結果。此外，為了改善整體預測結果，請務必提供合理的可視區域，例如您透過平移或縮放地圖設定的可視區域，或是開發人員根據裝置位置和半徑設定的可視區域。如果沒有設定半徑，系統會將 5 公里視為 Basic Place Autocomplete 元素的合理預設值。請勿將可視區域設為下列值：半徑為零 (單一點)、範圍僅有幾公尺 (小於 100 公尺)，或是橫跨全球。

按國家/地區限制 Place Search

如要將 Place Search 限制在一或多個特定國家/地區，請使用 includedRegionCodes 屬性指定國家/地區代碼，如以下程式碼片段所示：

const pac = new google.maps.places.BasicPlaceAutocompleteElement({
  includedRegionCodes: ['us', 'au'],
});

將 Place Search 限制在地圖邊界內

如要將 Place Search 限制在地圖邊界內，請使用 locationRestrictions 屬性新增邊界，如以下程式碼片段所示：

const pac = new google.maps.places.BasicPlaceAutocompleteElement({
  locationRestriction: map.getBounds(),
});

限制地圖範圍時，請務必新增事件監聽器，在範圍變更時加以更新：

map.addListener('bounds_changed', () => {
  autocomplete.locationRestriction = map.getBounds();
});

如要移除 locationRestriction，請設為 null。

自訂調整 Place Search 結果

使用 locationBias 屬性並傳遞半徑，將 Place Search 結果自訂調整為僅限某個圓形區域，如下所示：

const autocomplete = new google.maps.places.BasicPlaceAutocompleteElement({
  locationBias: {radius: 100, center: {lat: 50.064192, lng: -130.605469}},
});

如要移除 locationBias，請設為 null。

將 Place Search 結果限制為特定類型

使用 includedPrimaryTypes 屬性並指定一或多個類型，將 Place Search 結果限制為特定類型的地點，如下所示：

const autocomplete = new google.maps.places.BasicPlaceAutocompleteElement({
  includedPrimaryTypes: ['establishment'],
});

如需支援類型的完整清單，請參閱地點類型表 A 和 B。

設定「地點要求」元素

新增監聽器，在使用者選取預測結果時更新地點要求元素： 

// Event listener for when a place is selected from the autocomplete list.
placeAutocompleteElement.addEventListener('gmp-select', (event) => {
    // Reset marker and InfoWindow, and prepare the details element.
    placeDetailsParent.appendChild(placeDetailsElement);
    placeDetailsElement.style.display = 'block';
    advancedMarkerElement.position = null;
    infoWindow.close();
    // Request details for the selected place.
    const placeDetailsRequest = placeDetailsElement.querySelector('gmp-place-details-place-request');
    placeDetailsRequest.place = event.place.id;
});
index.js

本例顯示如何在 Google 地圖中加入 Basic Autocomplete 元素。

JavaScript

const placeAutocompleteElement = document.querySelector('gmp-basic-place-autocomplete');
const placeDetailsElement = document.querySelector('gmp-place-details-compact');
const placeDetailsParent = placeDetailsElement.parentElement;
const gmpMapElement = document.querySelector('gmp-map');
async function initMap() {
    // Asynchronously load required libraries from the Google Maps JS API.
    await google.maps.importLibrary('places');
    const { AdvancedMarkerElement } = (await google.maps.importLibrary('marker'));
    const { InfoWindow } = (await google.maps.importLibrary('maps'));
    // Get the initial center directly from the gmp-map element's property.
    const center = gmpMapElement.center;
    // Set the initial location bias for the autocomplete element.
    placeAutocompleteElement.locationBias = center;
    // Update the map object with specified options.
    const map = gmpMapElement.innerMap;
    map.setOptions({
        clickableIcons: false,
        mapTypeControl: false,
        streetViewControl: false,
    });
    // Create an advanced marker to show the location of a selected place.
    const advancedMarkerElement = new AdvancedMarkerElement({
        map: map,
        collisionBehavior: google.maps.CollisionBehavior.REQUIRED_AND_HIDES_OPTIONAL,
    });
    // Create an InfoWindow to hold the place details component.
    const infoWindow = new InfoWindow({
        minWidth: 360,
        disableAutoPan: true,
        headerDisabled: true,
        pixelOffset: new google.maps.Size(0, -10),
    });
    // Event listener for when a place is selected from the autocomplete list.
    placeAutocompleteElement.addEventListener('gmp-select', (event) => {
        // Reset marker and InfoWindow, and prepare the details element.
        placeDetailsParent.appendChild(placeDetailsElement);
        placeDetailsElement.style.display = 'block';
        advancedMarkerElement.position = null;
        infoWindow.close();
        // Request details for the selected place.
        const placeDetailsRequest = placeDetailsElement.querySelector('gmp-place-details-place-request');
        placeDetailsRequest.place = event.place.id;
    });
    // Event listener for when the place details have finished loading.
    placeDetailsElement.addEventListener('gmp-load', () => {
        const location = placeDetailsElement.place.location;
        // Position the marker and open the InfoWindow at the place's location.
        advancedMarkerElement.position = location;
        infoWindow.setContent(placeDetailsElement);
        infoWindow.open({
            map,
            anchor: advancedMarkerElement,
        });
        map.setCenter(location);
    });
    // Event listener to close the InfoWindow when the map is clicked.
    map.addListener('click', () => {
        infoWindow.close();
        advancedMarkerElement.position = null;
    });
    // Event listener for when the map finishes moving (panning or zooming).
    map.addListener('idle', () => {
        const newCenter = map.getCenter();
        // Update the autocomplete's location bias to a 10km radius around the new map center.
        placeAutocompleteElement.locationBias = new google.maps.Circle({
            center: {
                lat: newCenter.lat(),
                lng: newCenter.lng(),
            },
            radius: 10000, // 10km in meters.
        });
    });
}
initMap();
index.js

CSS

html,
body {
  height: 100%;
  margin: 0;
  padding: 0;
}

gmp-map {
  height: 100%;
}

gmp-basic-place-autocomplete {
  position: absolute;
  height: 30px;
  width: 500px;
  top: 10px;
  left: 10px;
  box-shadow: 4px 4px 5px 0px rgba(0, 0, 0, 0.2);
  color-scheme: light;
  border-radius: 10px;
}
style.css

HTML

<html>
  <head>
    <title>Basic Place Autocomplete map</title>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
    <!-- prettier-ignore -->
    <script>
        (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})
        ({key: "AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8", v: "weekly"});
    </script>
  </head>
  <body>
    <gmp-map zoom="12" center="37.4220656,-122.0840897" map-id="DEMO_MAP_ID">
      <gmp-basic-place-autocomplete
        slot="control-inline-start-block-start"></gmp-basic-place-autocomplete>
    </gmp-map>
    <!-- Use inline styles to configure the Place Details Compact element because
     it will be placed within the info window, and info window content is inside 
     the shadow DOM when using <gmp-map> -->
    <gmp-place-details-compact
      orientation="horizontal"
      style="width: 400px;
      display: none;
      border: none;
      padding: 0;
      margin: 0;
      background-color: transparent;
      color-scheme: light;">
      <gmp-place-details-place-request></gmp-place-details-place-request>
      <gmp-place-standard-content></gmp-place-standard-content>
    </gmp-place-details-compact>
  </body>
</html>
index.html

試用範例