Autocomplete Data (new)

AutocompleteSuggestion 類別

google.maps.places.AutocompleteSuggestion class

自動完成建議結果。

撥打 const {AutocompleteSuggestion} = await google.maps.importLibrary("places") 即可存取。
請參閱「Maps JavaScript API 中的程式庫」。
fetchAutocompleteSuggestions
fetchAutocompleteSuggestions(autocompleteRequest)
參數： 
傳回值：  Promise<{suggestions:Array<AutocompleteSuggestion>}>
擷取 AutocompleteSuggestions 清單。

如果要求中提供 AutocompleteRequest.sessionToken，系統會在第一次呼叫 Place.fetchFields 時自動納入該工作階段權杖，並在結果 PlacePrediction 中，對 PlacePrediction.toPlace 傳回的每個 Place 執行這項操作。
placePrediction
類型：  PlacePrediction optional
包含傳回結果的使用者可解讀名稱。如果是機構結果，通常會顯示商家名稱和地址。

如果在用於擷取這個 AutocompleteSuggestion 的 AutocompleteRequest 中提供 AutocompleteRequest.sessionToken，當您在 PlacePrediction.toPlace 呼叫傳回的 Place 上首次呼叫 Place.fetchFields 時，系統會自動加入相同權杖。

AutocompleteRequest interface

google.maps.places.AutocompleteRequest 介面

AutocompleteSuggestion.fetchAutocompleteSuggestions 的要求介面。
input
類型：  string
要搜尋的文字字串。
includedPrimaryTypes optional
類型：  Array<string> optional
包含主要地點類型 (例如「restaurant」或「gas_station」)。

只有當地點的主要類型包含在此清單中時，系統才會傳回地點。最多可指定 5 個值。如未指定類型，系統會傳回所有地點類型。
includedRegionCodes optional
類型：  Array<string> optional
只納入指定區域的結果，最多可指定 15 個 CLDR 雙字元區域代碼。如果集合為空白，系統不會限制結果。如果同時設定 locationRestriction 和 includedRegionCodes，結果會位於交集區域。
inputOffset optional
類型：  number optional
以零為基準的 Unicode 字元位移值 input，表示 input 中的游標位置。游標位置可能會影響系統傳回的預測結果。如未指定，則預設為 input 的長度。
language optional
類型：  string optional
傳回結果時使用的語言。系統會預設為瀏覽器的偏好語言。如果 input 使用的語言與 language 不同，或是傳回的地點沒有從當地語言到 language 的翻譯，結果可能會混用多種語言。
locationBias optional
類型：  LocationBias optional
針對指定地點調整結果。

最多只能設定 locationBias 或 locationRestriction 其中一個。如果兩者皆未設定，系統會根據 IP 位址調整結果，也就是將 IP 位址對應至不精確的位置，並做為調整信號。
locationRestriction optional
類型：  LocationRestriction optional
將結果限制在指定地點。

最多只能設定 locationBias 或 locationRestriction 其中一個。如果兩者皆未設定，系統會根據 IP 位址調整結果，也就是將 IP 位址對應至不精確的位置，並做為調整信號。
origin optional
類型：  LatLng|LatLngLiteral optional
計算到目的地 (以 PlacePrediction.distanceMeters 形式傳回) 的測地距離時，使用的原點。如果省略這個值，系統就不會傳回測地距離。
region optional
類型：  string optional
區碼，指定為 CLDR 雙字元區碼。這會影響地址格式、結果排名，以及可能影響傳回的結果。這不會將結果限制在指定區域。
sessionToken optional
類型：  AutocompleteSessionToken optional
這個符記會識別自動完成工作階段，以用於計費。透過 AutocompleteSessionToken 產生新的工作階段符記。

工作階段是從使用者輸入查詢時開始，到使用者選取地點並撥打電話 Place.fetchFields 時結束。在每個工作階段中，使用者可以輸入多筆查詢，最終呼叫一次 fetchFields。工作階段中每項要求使用的憑證，都必須屬於同一個 Google Cloud 控制台專案。工作階段結束後，符記就會失效。您的應用程式必須為每個工作階段產生新的符記。如果省略 sessionToken 參數或重複使用工作階段符記，系統會視為未提供工作階段符記，並針對工作階段收費 (每個要求分別收費)。

如果在對 AutocompleteSuggestion.fetchAutocompleteSuggestions 的要求中提供工作階段權杖，系統會自動在第一個 fetchFields 呼叫中加入相同權杖，並在其中一個產生的 AutocompleteSuggestion 上呼叫 PlacePrediction.toPlace 時傳回 Place。

建議遵循下列準則：
  • 在所有 Place Autocomplete 呼叫中使用工作階段符記。
  • 為每個工作階段產生新的符記。
  • 請務必針對每個新的工作階段傳遞不重複的工作階段符記。如果多個工作階段使用同一個符記，則每個要求會分別計費。

AutocompleteSessionToken class

google.maps.places.AutocompleteSessionToken class

代表用於追蹤自動完成工作階段的工作階段符記。

撥打 const {AutocompleteSessionToken} = await google.maps.importLibrary("places") 即可存取。
請參閱「Maps JavaScript API 中的程式庫」。
AutocompleteSessionToken
AutocompleteSessionToken()
參數：無
用來建立 AutocompleteSessionToken 的新例項。

PlacePrediction 類別

google.maps.places.PlacePrediction class

Place Autocomplete 預測結果的預測結果。

撥打 const {PlacePrediction} = await google.maps.importLibrary("places") 即可存取。
請參閱「Maps JavaScript API 中的程式庫」。
distanceMeters
類型：  number optional
如果指定 origin，則為從 origin 開始的測地線長度 (以公尺為單位)。
mainText
類型：  FormattableText optional
代表地點名稱。
placeId
類型：  string
建議地點的專屬 ID。這個 ID 可用於接受地點 ID 的其他 API。
secondaryText
類型：  FormattableText optional
代表其他消歧特徵 (例如城市或區域)，可進一步識別地點。
text
類型：  FormattableText
包含傳回結果的使用者可解讀名稱。如果是機構結果，通常會顯示商家名稱和地址。

text 適用於想顯示單一 UI 元素的開發人員。如果開發人員想顯示兩個獨立但相關的 UI 元素，可以改用 PlacePrediction.mainText 和 PlacePrediction.secondaryText。
types
類型：  Array<string>
適用於這個地點的類型清單，請參閱 https://developers.google.com/maps/documentation/places/web-service/place-types 的表 A 或表 B。
BetafetchAddressValidation
fetchAddressValidation(request)
參數： 
傳回值：  Promise<AddressValidation>
傳送與這個自動完成工作階段相關聯的地址驗證要求 (在內部填入自動完成工作階段符記)。系統不會自動納入 PlacePrediction 中的地點資訊，這項便利的方法可協助管理 Autocomplete 工作階段。
toPlace
toPlace()
參數：無
傳回值：  Place
傳回這個 PlacePrediction 的 Place 表示法。如要取得完整的地點詳細資料，必須後續呼叫 Place.fetchFields。

如果在用於擷取這個 PlacePrediction 的 AutocompleteRequest 中提供 AutocompleteRequest.sessionToken，系統會在呼叫 fetchFields 時自動加入相同權杖。

此外，使用 PlaceAutocompleteElement 時，對 PlacePrediction.toPlace 傳回的 Place 進行第一次 Place.fetchFields 呼叫時，會自動納入工作階段權杖。

StringRange class

google.maps.places.StringRange class

識別指定文字中的子字串。

撥打 const {StringRange} = await google.maps.importLibrary("places") 即可存取。
請參閱「Maps JavaScript API 中的程式庫」。
endOffset
類型：  number
子字串最後一個 Unicode 字元的零起點位移 (不含)。
startOffset
類型：  number
子字串第一個 Unicode 字元的位移值 (從零算起，含該字元)。

FormattableText class

google.maps.places.FormattableText class

代表地點預測結果的文字。你可以直接使用或設定格式。

撥打 const {FormattableText} = await google.maps.importLibrary("places") 即可存取。
請參閱「Maps JavaScript API 中的程式庫」。
matches
類型：  Array<StringRange>
字串範圍清單，用於識別輸入要求在 FormattableText.text 中相符的位置。這些範圍可用於格式化 text 的特定部分。如果系統是根據字串比對以外的條件 (例如拼寫校正或音譯) 判斷是否相符，子字串可能不會與 AutocompleteRequest.input 完全相符。這些值是 FormattableText.text 的 Unicode 字元偏移。系統保證範圍會依遞增的位移值排序。
text
類型：  string
可直接使用或以 FormattableText.matches 格式化的文字。