Places Widgets

PlaceAutocompleteElement 類別

google.maps.places.PlaceAutocompleteElement class

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

自訂元素：
<gmp-place-autocomplete name="string" requested-language="string" requested-region="string" types="type1 type2 type3..."></gmp-place-autocomplete>

這個類別會擴充 HTMLElement。

這個類別會實作 PlaceAutocompleteElementOptions。

請呼叫 const {PlaceAutocompleteElement} = await google.maps.importLibrary("places") 存取。請參閱「Maps JavaScript API 中的程式庫」。
PlaceAutocompleteElement
PlaceAutocompleteElement(options)
參數： 
componentRestrictions
類型：  ComponentRestrictions optional
元件限制。元件限制可用於限制預測結果，只限於父項元件內的預測結果。例如國家/地區。
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-placeautocomplete name="string"></gmp-placeautocomplete>
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>
types
類型：  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 中有任何額外文字，則會位於 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-placeselect
function(placeAutocompletePlaceSelectEvent)
引數： 
使用者選取地點預測結果時，系統會觸發這項事件。包含 Place 物件。
gmp-requesterror
function(placeAutocompleteRequestErrorEvent)
引數： 
當後端要求遭到拒絕 (例如 API 金鑰不正確) 時，系統就會觸發這項事件。這個事件不會向上傳遞。

PlaceAutocompleteElementOptions 介面

google.maps.places.PlaceAutocompleteElementOptions 介面

建構 PlaceAutocompleteElement 的選項。
componentRestrictions optional
類型：  ComponentRestrictions optional
查看「PlaceAutocompleteElement.componentRestrictions」
locationBias optional
類型：  LocationBias optional
查看「PlaceAutocompleteElement.locationBias」
locationRestriction optional
類型：  LocationRestriction optional
查看「PlaceAutocompleteElement.locationRestriction」
requestedLanguage optional
類型：  string optional
查看「PlaceAutocompleteElement.requestedLanguage」
requestedRegion optional
類型：  string optional
查看「PlaceAutocompleteElement.requestedRegion」
types optional
類型：  Array<string> optional
查看「PlaceAutocompleteElement.types」

PlaceAutocompletePlaceSelectEvent 類別

google.maps.places.PlaceAutocompletePlaceSelectEvent class

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

這個類別會擴充 Event。

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

PlaceAutocompleteRequestErrorEvent 類別

google.maps.places.PlaceAutocompleteRequestErrorEvent class

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

這個類別會擴充 Event。

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

PlaceDetailsElement 類別

google.maps.places.PlaceDetailsElement class

用來顯示地點詳細資料的 HTML 元素。請使用 configureFromPlace() 或 configureFromLocation() 方法指定要轉譯的內容。如要使用 Place Details 元素，請在 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> 載入及轉譯地點資料後，系統會解析的承諾。
使用反向地理編碼，從 LatLng 設定小工具。
configureFromPlace
configureFromPlace(place)
參數： 
  • place：Place|{id:string} 要算繪詳細資料的位置。
傳回值：  Promise<void> 載入及轉譯地點資料後，系統會解析的承諾。
從 Place 物件或 Place ID 設定小工具。
BetaremoveEventListener
removeEventListener(type, listener[, options])
參數： 
傳回值：  void
從目標中移除先前使用 addEventListener 註冊的事件監聽器。請參閱 removeEventListener
gmp-load
function(event)
引數： 
當元素載入並轉譯其內容時，系統會觸發此事件。這個事件不會向上傳遞。
gmp-requesterror
function(event)
引數： 
當後端要求遭到拒絕 (例如 API 金鑰不正確) 時，系統就會觸發這項事件。這個事件不會向上傳遞。

PlaceDetailsElementOptions 介面

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 類別

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> 載入及轉譯地點資料後，系統會解析的承諾。
設定小工具，以便顯示 Places Text Search API 要求的搜尋結果。
configureFromSearchNearbyRequest
configureFromSearchNearbyRequest(request)
參數： 
  • request：SearchNearbyRequest 要算繪結果的請求。SearchNearbyRequest 的 fields 屬性並非必要。
傳回值：  Promise<void> 載入及轉譯地點資料後，系統會解析的承諾。
設定小工具，以便顯示 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 介面

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、位置和檢視區範圍。

Autocomplete 類別

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
在成功擷取詳細資料時，傳回要在詳細資料回應中納入的地點欄位。如需欄位清單，請參閱 PlaceResult。
getPlace
getPlace()
參數：無
傳回值：  PlaceResult 使用者所選的地點。
如果詳細資料已成功擷取，則會傳回使用者選取的地點詳細資料。否則會傳回 Stub Place 物件，並將 name 屬性設為輸入欄位的目前值。
setBounds
setBounds(bounds)
參數： 
傳回值：無
設定要傳回地點結果的偏好地區。結果可能會優先 (但不限於) 顯示這個區域。
setComponentRestrictions
setComponentRestrictions(restrictions)
參數： 
傳回值：無
設定元件限制。元件限制可用於限制預測結果，只限於父項元件內的預測結果。例如國家/地區。
setFields
setFields(fields)
參數： 
  • fields：Array<string> optional
傳回值：無
在成功擷取詳細資料時，設定要納入 Place 詳細資料回應的欄位。如需欄位清單，請參閱 PlaceResult。
setOptions
setOptions(options)
參數： 
傳回值：無
setTypes
setTypes(types)
參數： 
  • types：Array<string> optional 要納入的預測類型。
傳回值：無
設定要傳回的預測類型。如要瞭解支援的類型，請參閱 開發人員指南。如果沒有指定類型，系統就會傳回所有類型。
繼承： addListener、bindTo、get、notify、set、setValues、unbind、unbindAll
place_changed
function()
引數：無
當使用者選取的地點提供 PlaceResult 時，系統會觸發此事件。
如果使用者輸入控制項未建議的地點名稱，然後按下 Enter 鍵，或是 Places Details 要求失敗，PlaceResult 就會在 name 屬性中包含使用者輸入內容，且未定義其他屬性。

AutocompleteOptions 介面

google.maps.places.AutocompleteOptions 介面

可在 Autocomplete 物件上設定的選項。
bounds optional
類型：  LatLngBounds|LatLngBoundsLiteral optional
用於搜尋地點的區域。
componentRestrictions optional
類型：  ComponentRestrictions optional
元件限制。元件限制可用於限制預測結果，只限於父項元件內的預測結果。例如國家/地區。
fields optional
類型：  Array<string> optional
在成功擷取詳細資料時，要納入詳細資料回應中地點的欄位，並計費。如果傳入 ['ALL']，系統會傳回所有可用的欄位並據此收費 (不適用於正式環境部署作業)。如需欄位清單，請參閱 PlaceResult。您可以使用點號路徑 (例如 "geometry.location") 指定巢狀欄位。預設值為 ['ALL']。
placeIdOnly optional
類型：  boolean optional
是否只擷取地點 ID。在觸發 place_changed 事件時提供的 PlaceResult 只會包含 place_id、類型和名稱欄位，以及 Autocomplete 服務傳回的 place_id、類型和說明。預設為停用。
strictBounds optional
類型：  boolean optional
布林值，表示 Autocomplete 小工具只會在查詢時傳回位於 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 介面

google.maps.places.SearchBoxOptions 介面

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