Places Widgets

PlaceAutocompleteElement 類別

google.maps.places.PlaceAutocompleteElement class

PlaceAutocompleteElement 是 HTMLElement 子類別，可為 Places Autocomplete API 提供 UI 元件。

自訂元素：
<gmp-place-autocomplete included-primary-types="type1 type2 type3..." included-region-codes="c1 c2 c3..." name="string" origin="lat,lng|lat,lng,altitude" requested-language="string" requested-region="string" unit-system="metric|imperial" types="type1 type2 type3..."></gmp-place-autocomplete>

這個類別會擴充 HTMLElement。

這個類別會實作 PlaceAutocompleteElementOptions。

撥打 const {PlaceAutocompleteElement} = await google.maps.importLibrary("places") 即可存取。
請參閱「Maps JavaScript API 中的程式庫」。
PlaceAutocompleteElement
PlaceAutocompleteElement(options)
參數： 
AlphaincludedPrimaryTypes
類型：  Array<string> optional
包含主要地點類型 (例如「restaurant」或「gas_station」)。

只有當地點的主要類型包含在此清單中時，系統才會傳回地點。最多可指定 5 個值。如未指定類型，系統會傳回所有地點類型。
HTML 屬性：
  • <gmp-place-autocomplete included-primary-types="type1 type2 type3..."></gmp-place-autocomplete>
AlphaincludedRegionCodes
類型：  Array<string> optional
只納入指定區域的結果，最多可指定 15 個 CLDR 雙字元區域代碼。如果集合為空白，系統不會限制結果。如果同時設定 locationRestriction 和 includedRegionCodes，結果會位於交集區域。
HTML 屬性：
  • <gmp-place-autocomplete included-region-codes="c1 c2 c3..."></gmp-place-autocomplete>
locationBias
類型：  LocationBias optional
搜尋地點時使用的軟性邊界或提示。
locationRestriction
類型：  LocationRestriction optional
用來限制搜尋結果的範圍。
name
類型：  string optional
輸入元素要使用的名稱。詳情請參閱 https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#name。與輸入內容的名稱屬性行為相同。請注意，提交表單時會使用這個名稱。詳情請參閱 https://developer.mozilla.org/en-US/docs/Web/HTML/Element/form。
HTML 屬性：
  • <gmp-place-autocomplete name="string"></gmp-place-autocomplete>
Alphaorigin
計算距離的起點。如未指定，系統就不會計算距離。系統不會使用海拔高度 (如有) 進行計算。
HTML 屬性：
  • <gmp-place-autocomplete origin="lat,lng|lat,lng,altitude"></gmp-place-autocomplete>
requestedLanguage
類型：  string optional
盡可能提供語言 ID，指出應以哪種語言傳回結果。系統可能會優先顯示所選語言的結果，但建議不限於該語言。請參閱支援語言清單。
HTML 屬性：
  • <gmp-place-autocomplete requested-language="string"></gmp-place-autocomplete>
requestedRegion
類型：  string optional
用於格式化和篩選結果的區域代碼。這不會將建議限制在該國家/地區。區碼接受 ccTLD (「頂層網域」) 的兩位字元值。多數 ccTLD 代碼與 ISO 3166-1 代碼相同，只有少數例外。舉例來說，英國的 ccTLD 是「uk」(.co.uk)，而 ISO 3166-1 代碼是「gb」(技術上是指「大不列顛及北愛爾蘭聯合王國」實體)。
HTML 屬性：
  • <gmp-place-autocomplete requested-region="string"></gmp-place-autocomplete>
AlphaunitSystem
類型：  UnitSystem optional
顯示距離時使用的單位制。如未指定，系統會根據 requestedRegion 決定單位系統。
HTML 屬性：
  • <gmp-place-autocomplete unit-system="metric|imperial"></gmp-place-autocomplete>
BetacomponentRestrictions
類型：  ComponentRestrictions optional
元件限制。元件限制用於將預測結果限制在父項元件內。例如國家/地區。
Betatypes
類型：  Array<string> optional
要傳回的預測類型。如要瞭解支援的類型，請參閱 開發人員指南。如果未指定類型，系統會傳回所有類型。
HTML 屬性：
  • <gmp-place-autocomplete types="type1 type2 type3..."></gmp-place-autocomplete>
prediction-item
預測下拉式選單中的項目，代表單一預測。
prediction-item-icon
顯示在預測查詢字串清單中每個項目左側的圖示。
prediction-item-main-text
預測項目的一部分，是預測結果的主要文字。就地理位置而言，這包含地方資訊名稱 (例如「Sydney」) 或街道名稱及門牌號碼 (例如「10 King Street」)。預設情況下，prediction-item-main-text 為黑色。如果預測項目中有任何額外文字，則會位於 prediction-item-main-text 之外，並沿用 prediction-item 的樣式。在預設情況下會以灰色顯示。這組額外文字通常是地址。
prediction-item-match
傳回的預測查詢字串中，與使用者輸入文字相符的部分。根據預設，這組相符文字會以粗體字標示。請注意，相符文字可能會在 prediction-item 內的任何位置，不一定是 prediction-item-main-text 的一部分。
prediction-item-selected
使用者透過鍵盤導覽至的項目。注意：選取的項目會受到這部分樣式和預測項目部分樣式的影響。
prediction-list
包含「地方資訊自動完成」服務所傳回預測查詢字串清單的視覺元素。這份清單會以下拉式選單的形式，顯示在 PlaceAutocompleteElement 下方。
BetaaddEventListener
addEventListener(type, listener[, options])
參數： 
  • type：string代表要監聽的事件類型，且區分大小寫。
  • listener：EventListener|EventListenerObject接收通知的物件。這必須是函式或包含 handleEvent 方法的物件
  • options：boolean|AddEventListenerOptions optional請參閱選項。自訂事件僅支援 capture 和 passive。
傳回值：  void
設定函式，每當指定事件傳送至目標時，系統就會呼叫該函式。請參閱 addEventListener。
BetaremoveEventListener
removeEventListener(type, listener[, options])
參數： 
傳回值：  void
從目標中移除先前透過 addEventListener 註冊的事件監聽器。請參閱「removeEventListener」。
gmp-error
function(errorEvent)
引數： 
當後端要求遭到拒絕時 (例如 API 金鑰不正確)，就會觸發這項事件。這個事件不會冒泡。
gmp-select
function(placePredictionSelectEvent)
引數： 
使用者選取地點預測時，系統會觸發這項事件。內含可轉換為 Place 物件的 PlacePrediction 物件。
gmp-placeselect
function(placeAutocompletePlaceSelectEvent)
引數： 
使用者選取地點預測時，系統會觸發這項事件。包含 Place 物件。

PlaceAutocompleteElementOptions interface

google.maps.places.PlaceAutocompleteElementOptions 介面

建構 PlaceAutocompleteElement 的選項。如要瞭解各項屬性，請參閱 PlaceAutocompleteElement 類別中同名的屬性。
BetacomponentRestrictions optional
類型：  ComponentRestrictions optional
AlphaincludedPrimaryTypes optional
類型：  Array<string> optional
AlphaincludedRegionCodes optional
類型：  Array<string> optional
locationBias optional
類型：  LocationBias optional
locationRestriction optional
類型：  LocationRestriction optional
name optional
類型：  string optional
Alphaorigin optional
requestedLanguage optional
類型：  string optional
Betatypes optional
類型：  Array<string> optional
AlphaunitSystem optional
類型：  UnitSystem optional

PlaceAutocompletePlaceSelectEvent class

google.maps.places.PlaceAutocompletePlaceSelectEvent class

使用者透過 Place Autocomplete 元素選取地點後，系統就會建立這項事件。使用 event.place 存取選取範圍。

這個類別會擴充 Event。

撥打 const {PlaceAutocompletePlaceSelectEvent} = await google.maps.importLibrary("places") 即可存取。
請參閱「Maps JavaScript API 中的程式庫」。
Betaplace
類型：  Place

PlacePredictionSelectEvent class

google.maps.places.PlacePredictionSelectEvent class

使用者透過 PlaceAutocompleteElement 選取預測項目後，系統就會建立這個事件。使用 event.placePrediction 存取選取範圍。

這個類別會擴充 Event。

撥打 const {PlacePredictionSelectEvent} = await google.maps.importLibrary("places") 即可存取。
請參閱「Maps JavaScript API 中的程式庫」。
placePrediction
類型：  PlacePrediction

PlaceAutocompleteRequestErrorEvent class

google.maps.places.PlaceAutocompleteRequestErrorEvent class

網路要求發生問題時，PlaceAutocompleteElement 會發出這個事件。

這個類別會擴充 Event。

撥打 const {PlaceAutocompleteRequestErrorEvent} = await google.maps.importLibrary("places") 即可存取。
請參閱「Maps JavaScript API 中的程式庫」。

PlaceDetailsElement class

google.maps.places.PlaceDetailsElement class

顯示地點詳細資料的 HTML 元素。使用 configureFromPlace() 或 configureFromLocation() 方法指定要算繪的內容。如要使用地點詳細資料元素，請在 Google Cloud 控制台中，為專案啟用 Places UI Kit API。

自訂元素：
<gmp-place-details size="small"></gmp-place-details>

這個類別會擴充 HTMLElement。

這個類別會實作 PlaceDetailsElementOptions。

撥打 const {PlaceDetailsElement} = await google.maps.importLibrary("places") 即可存取。
請參閱「Maps JavaScript API 中的程式庫」。
PlaceDetailsElement
PlaceDetailsElement([options])
參數： 
place
類型：  Place optional
僅供檢視。Place 物件，內含目前算繪地點的 ID、位置和可視區域。
size
類型：  PlaceDetailsSize optional
PlaceDetailsElement 的大小變體。根據預設，元素會顯示 PlaceDetailsSize.X_LARGE。
HTML 屬性：
  • <gmp-place-details size="small"></gmp-place-details>
  • <gmp-place-details size="medium"></gmp-place-details>
  • <gmp-place-details size="large"></gmp-place-details>
  • <gmp-place-details size="x-large"></gmp-place-details>
BetaaddEventListener
addEventListener(type, listener[, options])
參數： 
  • type：string代表要監聽的事件類型，且區分大小寫。
  • listener：EventListener|EventListenerObject接收通知的物件。這必須是函式或包含 handleEvent 方法的物件
  • options：boolean|AddEventListenerOptions optional請參閱選項。自訂事件僅支援 capture 和 passive。
傳回值：  void
設定函式，每當指定事件傳送至目標時，系統就會呼叫該函式。請參閱 addEventListener。
configureFromLocation
configureFromLocation(location)
參數： 
傳回值：  Promise<void> 載入及算繪地點資料後，系統會解析 Promise。
使用反向地理編碼，從 LatLng 設定小工具。
configureFromPlace
configureFromPlace(place)
參數： 
  • place：Place|{id:string}要顯示詳細資料的地點。
傳回值：  Promise<void> 載入及算繪地點資料後，系統會解析 Promise。
透過 Place 物件或地點 ID 設定小工具。
BetaremoveEventListener
removeEventListener(type, listener[, options])
參數： 
傳回值：  void
從目標中移除先前透過 addEventListener 註冊的事件監聽器。請參閱「removeEventListener」。
gmp-load
function(event)
引數： 
當元素載入並算繪內容時，系統會觸發這個事件。這個事件不會冒泡。
gmp-requesterror
function(event)
引數： 
當後端要求遭到拒絕時 (例如 API 金鑰不正確)，就會觸發這項事件。這個事件不會冒泡。

PlaceDetailsElementOptions interface

google.maps.places.PlaceDetailsElementOptions 介面

「PlaceDetailsElement」的選項。
size optional
類型：  PlaceDetailsSize optional
查看「PlaceDetailsElement.size」

PlaceDetailsSize 常數

google.maps.places.PlaceDetailsSize 常數

PlaceDetailsElement 的尺寸子類。

撥打 const {PlaceDetailsSize} = await google.maps.importLibrary("places") 即可存取。
請參閱「Maps JavaScript API 中的程式庫」。
LARGE 大型變體，包括大型圖片、基本資訊和聯絡資訊。
MEDIUM 中型變體，包含大型圖片和基本資訊。
SMALL 小型變化版本，包含小型圖片和基本資訊。
X_LARGE 特大變體，包括相片集錦、評論和詳細地點資訊。

PlaceListElement class

google.maps.places.PlaceListElement class

HTML 元素，可將地點搜尋結果顯示在清單中。使用 configureFromSearchByTextRequest() 或 configureFromSearchNearbyRequest() 方法，指定要用於顯示結果的要求。如要使用地點清單元素，請在 Google Cloud 控制台中，為專案啟用 Places UI Kit API。

自訂元素：
<gmp-place-list selectable></gmp-place-list>

這個類別會擴充 HTMLElement。

這個類別會實作 PlaceListElementOptions。

撥打 const {PlaceListElement} = await google.maps.importLibrary("places") 即可存取。
請參閱「Maps JavaScript API 中的程式庫」。
PlaceListElement
PlaceListElement([options])
參數： 
places
類型：  Array<Place>
僅供檢視。Place 物件陣列，內含目前算繪地點的 ID、位置和檢視區塊。
selectable
類型：  boolean
清單項目是否可選取。如果為 true，清單項目會是按鈕，點按時會分派 gmp-placeselect 事件。也支援無障礙鍵盤導覽和選取功能。
HTML 屬性：
  • <gmp-place-list selectable></gmp-place-list>
BetaaddEventListener
addEventListener(type, listener[, options])
參數： 
  • type：string代表要監聽的事件類型，且區分大小寫。
  • listener：EventListener|EventListenerObject接收通知的物件。這必須是函式或包含 handleEvent 方法的物件
  • options：boolean|AddEventListenerOptions optional請參閱選項。自訂事件僅支援 capture 和 passive。
傳回值：  void
設定函式，每當指定事件傳送至目標時，系統就會呼叫該函式。請參閱 addEventListener。
configureFromSearchByTextRequest
configureFromSearchByTextRequest(request)
參數： 
  • request：SearchByTextRequest用於算繪結果的要求。SearchByTextRequest 的 fields 屬性為選填。
傳回值：  Promise<void> 載入及算繪地點資料後，系統會解析 Promise。
設定小工具，以便從 Places Text Search API 要求算繪搜尋結果。
configureFromSearchNearbyRequest
configureFromSearchNearbyRequest(request)
參數： 
  • request：SearchNearbyRequest用於算繪結果的要求。SearchNearbyRequest 的 fields 屬性為選填。
傳回值：  Promise<void> 載入及算繪地點資料後，系統會解析 Promise。
設定小工具，以便從 Places Nearby Search API 要求轉譯搜尋結果。
BetaremoveEventListener
removeEventListener(type, listener[, options])
參數： 
傳回值：  void
從目標中移除先前透過 addEventListener 註冊的事件監聽器。請參閱「removeEventListener」。
gmp-load
function(event)
引數： 
當元素載入並算繪內容時，系統會觸發這個事件。這個事件不會冒泡。
gmp-placeselect
function(event)
引數： 
使用者選取地點時，系統會觸發這項事件。包含 Place 物件和清單中所選地點的索引。
gmp-requesterror
function(event)
引數： 
當後端要求遭到拒絕時 (例如 API 金鑰不正確)，就會觸發這項事件。這個事件不會冒泡。

PlaceListElementOptions interface

google.maps.places.PlaceListElementOptions 介面

「PlaceListElement」的選項。
selectable optional
類型：  boolean optional
查看「PlaceListElement.selectable」

PlaceListPlaceSelectEvent 類別

google.maps.places.PlaceListPlaceSelectEvent class

使用者選取地點時，PlaceListElement 會發出這個事件。

這個類別會擴充 Event。

撥打 const {PlaceListPlaceSelectEvent} = await google.maps.importLibrary("places") 即可存取。
請參閱「Maps JavaScript API 中的程式庫」。
index
類型：  number
所選地點的清單索引。
place
類型：  Place
Place 物件，內含所選地點的 ID、位置和可視區域。

自動完成 類別

google.maps.places.Autocomplete class

這個小工具會根據使用者輸入的文字提供地點預測結果。這個指令會附加至 text 類型的輸入元素，並監聽該欄位中的文字輸入內容。預測結果清單會以下拉式清單的形式顯示，並在輸入文字時更新。

這個類別會擴充 MVCObject。

撥打 const {Autocomplete} = await google.maps.importLibrary("places") 即可存取。
請參閱「Maps JavaScript API 中的程式庫」。
Autocomplete
Autocomplete(inputField[, opts])
參數： 
建立 Autocomplete 的新例項，並使用指定選項附加至指定輸入文字欄位。
getBounds
getBounds()
參數：無
傳回值：  LatLngBounds|undefined 偏差界限。
傳回預測結果的偏誤範圍。
getFields
getFields()
參數：無
傳回值：  Array<string>|undefined
成功擷取詳細資料時，傳回要在詳細資料回應中納入的 Place 欄位。如需欄位清單，請參閱 PlaceResult。
getPlace
getPlace()
參數：無
傳回值：  PlaceResult 使用者選取的地點。
如果成功擷取詳細資料，系統會傳回使用者選取的地點詳細資料。否則會傳回 Place 物件的存根，並將 name 屬性設為輸入欄位的目前值。
setBounds
setBounds(bounds)
參數： 
傳回值：無
設定要傳回地點結果的偏好區域。結果可能會優先 (但不限於) 顯示這個區域的地點。
setComponentRestrictions
setComponentRestrictions(restrictions)
參數： 
傳回值：無
設定元件限制。元件限制用於將預測結果限制在父項元件內。例如國家/地區。
setFields
setFields(fields)
參數： 
  • fields：Array<string> optional
傳回值：無
設定成功擷取詳細資料時，要在詳細資料回應中納入的地點欄位。如需欄位清單，請參閱 PlaceResult。
setOptions
setOptions(options)
參數： 
傳回值：無
setTypes
setTypes(types)
參數： 
  • types：Array<string> optional要納入的預測類型。
傳回值：無
設定要傳回的預測類型。如要瞭解支援的類型，請參閱 開發人員指南。如果未指定類型，系統會傳回所有類型。
已繼承： addListener、 bindTo、 get、 notify、 set、 setValues、 unbind、 unbindAll
place_changed
function()
引數：無
當使用者選取的地點提供 PlaceResult 時，系統會觸發這項事件。
如果使用者輸入控制項未建議的地點名稱並按下 Enter 鍵，或地點詳細資料要求失敗，則 PlaceResult 會在 name 屬性中包含使用者輸入的內容，且未定義其他屬性。

AutocompleteOptions 介面

google.maps.places.AutocompleteOptions 介面

可在 Autocomplete 物件上設定的選項。
bounds optional
類型：  LatLngBounds|LatLngBoundsLiteral optional
要搜尋地點的區域。
componentRestrictions optional
類型：  ComponentRestrictions optional
元件限制。元件限制用於將預測結果限制在父項元件內。例如國家/地區。
fields optional
類型：  Array<string> optional
成功擷取詳細資料時，詳細資料回應中要納入的 Place 欄位，這些欄位會產生費用。如果傳入 ['ALL']，系統會傳回所有可用的欄位並據此收費 (不適用於實際工作環境部署作業)。如需欄位清單，請參閱 PlaceResult。您可以使用點路徑指定巢狀欄位 (例如 "geometry.location")。預設值為 ['ALL']。
placeIdOnly optional
類型：  boolean optional
是否只擷取地點 ID。系統觸發 place_changed 事件時，可用的 PlaceResult 只會包含 place_id、types 和 name 欄位，以及 Autocomplete 服務傳回的 place_id、types 和 description。預設為停用。
strictBounds optional
類型：  boolean optional
布林值，表示 Autocomplete 小工具只能傳回查詢當下位於小工具界線內的地點。將 strictBounds 設為 false (預設值) 時，結果可能會優先 (但不限於) 顯示邊界內的地點。
types optional
類型：  Array<string> optional
要傳回的預測類型。如要瞭解支援的類型，請參閱 開發人員指南。如果未指定類型，系統會傳回所有類型。

google.maps.places.SearchBox class

這個小工具會根據使用者輸入的文字提供查詢預測。這個指令會附加至 text 類型的輸入元素，並監聽該欄位中的文字輸入內容。預測結果清單會以下拉式清單的形式顯示，並在輸入文字時更新。

這個類別會擴充 MVCObject。

撥打 const {SearchBox} = await google.maps.importLibrary("places") 即可存取。
請參閱「Maps JavaScript API 中的程式庫」。
SearchBox
SearchBox(inputField[, opts])
參數： 
建立 SearchBox 的新例項，並使用指定選項附加至指定輸入文字欄位。
getBounds
getBounds()
參數：無
傳回值：  LatLngBounds|undefined
傳回查詢預測結果的偏誤範圍。
getPlaces
getPlaces()
參數：無
傳回值：  Array<PlaceResult>|undefined
傳回使用者選取的查詢，用於 places_changed 事件。
setBounds
setBounds(bounds)
參數： 
傳回值：無
設定用於查詢預測偏誤的區域。結果只會優先顯示這個區域的地點，但不會完全限制於此。
已繼承： addListener、 bindTo、 get、 notify、 set、 setValues、 unbind、 unbindAll
places_changed
function()
引數：無
使用者選取查詢時會觸發此事件，getPlaces 則用於取得新地點。

SearchBoxOptions interface

google.maps.places.SearchBoxOptions 介面

可在 SearchBox 物件上設定的選項。
bounds optional
類型：  LatLngBounds|LatLngBoundsLiteral optional
要將查詢預測結果偏向的區域。預測結果可能會優先 (但不限於) 顯示這些邊界內的地點。