3D Maps

Map3DElement 類別

google.maps.maps3d.Map3DElement class

Map3DElement 是 3D 地圖檢視畫面的 HTML 介面。請注意，您必須設定 mode，3D 地圖才會開始算繪。

自訂元素：
<gmp-map-3d center="lat,lng,altitude" default-ui-hidden description="string" gesture-handling="auto" heading="number" internal-usage-attribution-ids="id1 id2" map-id="string" max-altitude="number" max-heading="number" max-tilt="number" min-altitude="number" min-heading="number" min-tilt="number" mode="hybrid" range="number" roll="number" tilt="number" default-ui-disabled></gmp-map-3d>

這個類別會擴充 HTMLElement。

這個類別會實作 Map3DElementOptions。

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

建構函式
Map3DElement	Map3DElement([options]) 參數：  options：Map3DElementOptions optional

屬性
bounds	類型：  LatLngBounds|LatLngBoundsLiteral optional 設定後，攝影機位置會限制在指定的經緯度範圍內。請注意，系統仍會算繪邊界外的物件。邊界可以同時限制經度和緯度，也可以只限制緯度或經度。如要設定僅限緯度的邊界，請分別使用 -180 和 180 的西經和東經。如要設定僅限經度的邊界，請分別使用 90 和 -90 的北緯和南緯。
center	類型：  LatLngAltitude|LatLngAltitudeLiteral optional 地圖中心點，以 LatLngAltitude 表示，其中高度是以公尺為單位，表示高於地面的高度。請注意，這不一定是攝影機的位置，因為 range 欄位會影響攝影機與地圖中心的距離。如未設定，則預設為 {lat: 0, lng: 0, altitude: 63170000}。高度上限為 63,170,000 公尺 (地球半徑乘以 10)。 HTML 屬性： <gmp-map-3d center="lat,lng,altitude"></gmp-map-3d>
defaultUIHidden	類型：  boolean optional 預設值： false 如果為 true，所有預設 UI 按鈕都會隱藏。 HTML 屬性： <gmp-map-3d default-ui-hidden></gmp-map-3d>
description	類型：  string optional 如果提供無障礙說明 (例如用於螢幕閱讀器)，系統會將該說明新增至地圖，並附上提供的值。 HTML 屬性： <gmp-map-3d description="string"></gmp-map-3d>
gestureHandling	類型：  GestureHandling optional 預設值： GestureHandling.GREEDY 控制協作手勢處理。如果設為 COOPERATIVE，則必須使用輔助鍵或雙指手勢，才能捲動地圖。如果設為 GREEDY，地圖元素上的使用者事件就無法捲動主機網頁。如果設為 AUTO，手勢處理方式會由主機頁面的捲動功能決定。 HTML 屬性： <gmp-map-3d gesture-handling="auto"></gmp-map-3d> <gmp-map-3d gesture-handling="cooperative"></gmp-map-3d> <gmp-map-3d gesture-handling="greedy"></gmp-map-3d>
heading	類型：  number optional 地圖的指南針方向 (以度為單位)，正北為零。如果沒有傾斜，任何滾動都會解讀為航向。 HTML 屬性： <gmp-map-3d heading="number"></gmp-map-3d>
internalUsageAttributionIds	類型：  Iterable<string> optional 在初始化工具中加入用量歸因 ID，協助 Google 瞭解哪些程式庫和範例對開發人員有幫助，例如標記叢集程式庫的使用情形。如要選擇不傳送用量歸因 ID，可以放心刪除這項屬性。系統只會傳送不重複的值。例項化後，系統可能會忽略對這個值的變更。 HTML 屬性： <gmp-map-3d internal-usage-attribution-ids="id1 id2"></gmp-map-3d>
language	類型：  string optional 嘗試用來顯示基本地圖的語言。載入 Maps JS API 時，預設會採用開發人員要求的語言。
mapId	類型：  string optional 指定地圖 ID，用於擷取地圖的雲端式地圖樣式設定。地圖初始化後，請勿設定這個屬性。因此，我們確保 mapId 僅在初始化期間設定，且不會將這個屬性發布至公開管道。 HTML 屬性： <gmp-map-3d map-id="string"></gmp-map-3d>
maxAltitude	類型：  number optional 地圖上顯示的最高海拔高度。有效值介於 0 至 63170000 公尺之間 (地球半徑乘以 10)。 HTML 屬性： <gmp-map-3d max-altitude="number"></gmp-map-3d>
maxHeading	類型：  number optional 地圖的最大朝向 (旋轉) 角度。有效值介於 0 到 360 度之間。minHeading 和 maxHeading 代表 <= 360 度的間隔，在這個間隔內可使用頭部動作。minHeading = 180 和 maxHeading = 90 可讓您前往 [0, 90] 和 [180, 360]。minHeading = 90 和 maxHeading = 180 將允許在 [90, 180] 中使用標題。 HTML 屬性： <gmp-map-3d max-heading="number"></gmp-map-3d>
maxTilt	類型：  number optional 地圖的最大入射角。有效值介於 0 到 90 度之間。 HTML 屬性： <gmp-map-3d max-tilt="number"></gmp-map-3d>
minAltitude	類型：  number optional 地圖上顯示的最低離地高度。有效值介於 0 至 63170000 公尺之間 (地球半徑乘以 10)。 HTML 屬性： <gmp-map-3d min-altitude="number"></gmp-map-3d>
minHeading	類型：  number optional 地圖的最小朝向 (旋轉) 角度。有效值介於 0 到 360 度之間。minHeading 和 maxHeading 代表 <= 360 度的間隔，在這個間隔內可使用頭部動作。minHeading = 180 和 maxHeading = 90 可讓您前往 [0, 90] 和 [180, 360]。minHeading = 90 和 maxHeading = 180 將允許在 [90, 180] 中使用標題。 HTML 屬性： <gmp-map-3d min-heading="number"></gmp-map-3d>
minTilt	類型：  number optional 地圖的最小入射角。有效值介於 0 到 90 度之間。 HTML 屬性： <gmp-map-3d min-tilt="number"></gmp-map-3d>
mode	類型：  MapMode optional 指定地圖的算繪模式。如未設定，地圖就不會顯示。 HTML 屬性： <gmp-map-3d mode="hybrid"></gmp-map-3d> <gmp-map-3d mode="satellite"></gmp-map-3d>
range	類型：  number optional 攝影機到地圖中心的距離 (以公尺為單位)。 HTML 屬性： <gmp-map-3d range="number"></gmp-map-3d>
region	類型：  string optional 嘗試轉譯基本地圖搜尋點的區域。載入 Maps JS API 時，預設為開發人員要求的區域。
roll	類型：  number optional 攝影機圍繞檢視向量的滾動角度，為避免混淆，如果沒有傾斜，任何滾轉都會解讀為航向。 HTML 屬性： <gmp-map-3d roll="number"></gmp-map-3d>
tilt	類型：  number optional 攝影機檢視向量的傾斜角度，如果檢視向量直接向下看地球，傾斜角度會是零度。如果檢視向量指向地球以外的方向，傾斜角度會是 180 度。 HTML 屬性： <gmp-map-3d tilt="number"></gmp-map-3d>
defaultUIDisabled	已淘汰：請改用 Map3DElement.defaultUIHidden。這項屬性將在日後推出的版本中移除。 類型：  boolean optional 預設值： false 如果設為 true，所有預設 UI 按鈕都會停用。不會停用鍵盤和手勢控制功能。 HTML 屬性： <gmp-map-3d default-ui-disabled></gmp-map-3d>

方法
addEventListener	addEventListener(type, listener[, options]) 參數：  type：string區分大小寫的字串，代表要監聽的事件類型。 listener：EventListener|EventListenerObject接收通知的物件。這必須是函式或具有 handleEvent 方法的物件 options：boolean|AddEventListenerOptions optional。查看選項。自訂事件僅支援 capture 和 passive。 傳回值：  void 設定函式，每當指定事件傳送至目標時，系統就會呼叫該函式。請參閱 addEventListener。
flyCameraAround	flyCameraAround(options) 參數：  options：FlyAroundAnimationOptions 傳回值：無 這個方法會讓攝影機在指定時間內繞著指定位置旋轉。動畫可重複播放指定的 FlyAroundAnimationOptions.repeatCount 次數。 攝影機會順時針移動。 這個方法是非同步的，因為地圖必須載入到一定程度，動畫才能開始。動畫開始後，方法就會傳回。 如果 FlyAroundAnimationOptions.repeatCount 次數為零，則不會旋轉，動畫會在開始後立即完成。
flyCameraTo	flyCameraTo(options) 參數：  options：FlyToAnimationOptions 傳回值：無 這個方法會以拋物線方式，在指定時間內將攝影機從目前位置移至指定終點位置。 這個方法是非同步的，因為地圖必須載入到一定程度，動畫才能開始。動畫開始後，方法就會傳回。
removeEventListener	removeEventListener(type, listener[, options]) 參數：  type：string這個字串會指定要移除事件監聽器的事件類型。 listener：EventListener|EventListenerObject要從事件目標中移除的事件處理常式事件監聽器。 options：boolean|EventListenerOptions optional。查看選項。 傳回值：  void 從目標中移除先前使用 addEventListener 註冊的事件監聽器。請參閱 removeEventListener。
stopCameraAnimation	stopCameraAnimation() 參數：無 傳回值：無 這個方法會停止任何可能正在執行的飛行動畫。相機會停留在動畫中間的任何位置，不會傳送到終點。 由於地圖必須載入一定程度後，動畫才能開始或停止，因此這個方法是非同步的。動畫停止後，方法就會傳回。

事件
gmp-animationend	function(animationEndEvent) 引數：  animationEndEvent：Event 飛行效果動畫結束時，系統會觸發這個事件。這個事件會透過 DOM 樹狀結構向上傳播。
gmp-centerchange	function(centerChangeEvent) 引數：  centerChangeEvent：Event Map3DElement 的 center 屬性變更時，就會觸發這個事件。
gmp-click	function(clickEvent) 引數：  clickEvent：LocationClickEvent|PlaceClickEvent 使用者點選 Map3DElement 元素時，系統會觸發這個事件。
gmp-error	function(mapInitializationErrorEvent) 引數：  mapInitializationErrorEvent：Event 地圖無法初始化時，就會觸發這個事件。
gmp-headingchange	function(headingChangeEvent) 引數：  headingChangeEvent：Event Map3DElement 的 heading 屬性變更時，就會觸發這個事件。
gmp-map-id-error	function(mapIdErrorEvent) 引數：  mapIdErrorEvent：Event Map3DElement 的 mapId 屬性無效時，就會觸發這個事件。
gmp-rangechange	function(rangeChangeEvent) 引數：  rangeChangeEvent：Event Map3DElement 的 range 屬性變更時，就會觸發這個事件。
gmp-rollchange	function(rollChangeEvent) 引數：  rollChangeEvent：Event Map3DElement 的 roll 屬性變更時，就會觸發這個事件。
gmp-steadychange	function(steadyChangeEvent) 引數：  steadyChangeEvent：SteadyChangeEvent Map3DElement 的穩定狀態變更時，系統會觸發這個事件。
gmp-tiltchange	function(tiltChangeEvent) 引數：  tiltChangeEvent：Event Map3DElement 的 tilt 屬性變更時，就會觸發這個事件。

Map3DElementOptions 介面

google.maps.maps3d.Map3DElementOptions 介面

Map3DElementOptions 物件，用於定義可在 Map3DElement 上設定的屬性。

屬性
bounds optional	類型：  LatLngBounds|LatLngBoundsLiteral optional 詳情請參閱《Map3DElement.bounds》。
center optional	類型：  LatLngAltitude|LatLngAltitudeLiteral optional 詳情請參閱《Map3DElement.center》。
defaultUIDisabled optional	已淘汰：請改用 Map3DElement.defaultUIHidden。這項屬性將在日後推出的版本中移除。 類型：  boolean optional 詳情請參閱《Map3DElement.defaultUIDisabled》。
defaultUIHidden optional	類型：  boolean optional 詳情請參閱《Map3DElement.defaultUIHidden》。
description optional	類型：  string optional 詳情請參閱《Map3DElement.description》。
gestureHandling optional	類型：  GestureHandling optional 詳情請參閱《Map3DElement.gestureHandling》。
heading optional	類型：  number optional 詳情請參閱《Map3DElement.heading》。
internalUsageAttributionIds optional	類型：  Iterable<string> optional 詳情請參閱《Map3DElement.internalUsageAttributionIds》。
language optional	類型：  string optional 詳情請參閱《Map3DElement.language》。
mapId optional	類型：  string optional 詳情請參閱《Map3DElement.mapId》。
maxAltitude optional	類型：  number optional 詳情請參閱《Map3DElement.maxAltitude》。
maxHeading optional	類型：  number optional 詳情請參閱《Map3DElement.maxHeading》。
maxTilt optional	類型：  number optional 詳情請參閱《Map3DElement.maxTilt》。
minAltitude optional	類型：  number optional 詳情請參閱《Map3DElement.minAltitude》。
minHeading optional	類型：  number optional 詳情請參閱《Map3DElement.minHeading》。
minTilt optional	類型：  number optional 詳情請參閱《Map3DElement.minTilt》。
mode optional	類型：  MapMode optional 詳情請參閱《Map3DElement.mode》。
range optional	類型：  number optional 詳情請參閱《Map3DElement.range》。
region optional	類型：  string optional 詳情請參閱《Map3DElement.region》。
roll optional	類型：  number optional 詳情請參閱《Map3DElement.roll》。
tilt optional	類型：  number optional 詳情請參閱《Map3DElement.tilt》。

MapMode 常數

google.maps.maps3d.MapMode 常數

指定地圖的算繪模式。

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

常數
HYBRID	這個地圖模式會在衛星或相片寫實圖像上，顯示主要街道的透明圖層。
SATELLITE	這個地圖模式會顯示衛星或擬真圖像 (如有)。

GestureHandling 常數

google.maps.maps3d.GestureHandling 常數

指定地圖元素應如何處理手勢事件。

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

常數
AUTO	這樣一來，地圖就能選擇要使用協作或貪婪手勢處理。如未指定，則會採用這項預設行為。 如果地圖佔據捲動父項 (通常是主機頁面) 的大部分空間，導致使用者無法捲動離開地圖查看其他內容，地圖就會進入協作模式。
COOPERATIVE	這會強制啟用合作模式，使用者必須使用輔助鍵或雙指手勢才能捲動地圖。
GREEDY	這會強制啟用貪婪模式，主機頁面無法透過地圖元素上的使用者事件捲動。

FlyAroundAnimationOptions 介面

google.maps.maps3d.FlyAroundAnimationOptions 介面

FlyCameraAround 動畫的自訂選項。

屬性
camera	類型：  CameraOptions 攝影機在軌道動畫期間應注視的中心點。請注意，地圖方向會隨著攝影機繞著這個中心點旋轉而改變。
durationMillis optional	類型：  number optional 一個動畫週期的時間長度 (以毫秒為單位)。
repeatCount optional	類型：  number optional 指定動畫應重複播放的次數。如果數字為零，動畫會在開始後立即完成。
rounds optional	已淘汰：請改用 FlyAroundAnimationOptions.repeatCount。 類型：  number optional 在指定時間長度內，圍繞中心旋轉的圈數。這項設定可控制整體旋轉速度。如果將負數傳遞至 rounds，攝影機就會逆時針旋轉，而非預設的順時針方向。

FlyToAnimationOptions 介面

google.maps.maps3d.FlyToAnimationOptions 介面

FlyCameraTo 動畫的自訂選項。

屬性
endCamera	類型：  CameraOptions 動畫結束時，攝影機應指向的位置。
durationMillis optional	類型：  number optional 動畫的時間長度 (以毫秒為單位)。如果時間長度為 0，攝影機會直接跳到結束位置。

CameraOptions 介面

google.maps.maps3d.CameraOptions 介面

CameraOptions 物件，用於定義可在相機物件上設定的屬性。攝影機物件可以是任何具有攝影機位置的物件，例如目前的地圖狀態，或未來要求的動畫狀態。

屬性
center optional	類型：  LatLngAltitude|LatLngAltitudeLiteral optional 詳情請參閱《Map3DElement.center》。
heading optional	類型：  number optional 詳情請參閱《Map3DElement.heading》。
range optional	類型：  number optional 詳情請參閱《Map3DElement.range》。
roll optional	類型：  number optional 詳情請參閱《Map3DElement.roll》。
tilt optional	類型：  number optional 詳情請參閱《Map3DElement.tilt》。

SteadyChangeEvent 類別

google.maps.maps3d.SteadyChangeEvent class

這個事件是透過監控 Map3DElement 的穩定狀態建立。這個事件會透過 DOM 樹狀結構向上傳播。

這個類別會擴充 Event。

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

屬性
isSteady	類型：  boolean 指出 Map3DElement 是否穩定 (即目前場景的所有算繪作業皆已完成)。

LocationClickEvent 類別

google.maps.maps3d.LocationClickEvent class

點按 Map3DElement 時，會建立這個事件。

這個類別會擴充 Event。

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

屬性
position	類型：  LatLngAltitude optional 事件發生時，游標下方的緯度/經度/高度。請注意，如果層級較粗略，傳回的資料準確度會較低。此外，從較高的相機位置點選水面時，系統可能會傳回海床海拔高度值。這個事件會透過 DOM 樹狀結構向上傳播。

PlaceClickEvent 類別

google.maps.maps3d.PlaceClickEvent class

使用者在Map3DElement上點選地點圖示時，就會觸發這項事件。如要避免顯示預設彈出式視窗，請對這個事件呼叫 preventDefault() 方法，防止 Map3DElement 處理該事件。

這個類別會擴充 LocationClickEvent。

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

屬性
placeId	類型：  string 地圖地圖項目的地點 ID。
沿用： position

方法
fetchPlace	fetchPlace() 參數：無 傳回值：  Promise<Place> 擷取這個地點 ID 的 Place。在產生的 Place 物件中，系統會填入 id 屬性。之後可透過 Place.fetchFields() 要求其他欄位，但須遵守 Places API 的一般啟用和計費規定。如果擷取 Place 時發生錯誤，系統會拒絕承諾。