Map3DElement 类
class
google.maps.maps3d.Map3DElement
extends HTMLElement
implements Map3DElementOptions
library "maps3d"
Map3DElement 是 3D 地图视图的 HTML 接口。请注意，必须设置 mode，3D 地图才能开始渲染。
<gmp-map-3d autofits-camera-animation="value-name" camera-position="lat,lng,altitude" center="lat,lng,altitude" color-scheme="value-name" default-ui-hidden description="string" fov="number" gesture-handling="value-name" heading="number" internal-usage-attribution-ids="id1 id2" map-id="string" max-altitude="number" max-heading="number" max-memory-megabytes="number" max-tilt="number" min-altitude="number" min-heading="number" min-tilt="number" mode="value-name" quality-mode="value-name" range="number" roll="number" tilt="number"> </gmp-map-3d>
const {Map3DElement} = await google.maps.importLibrary("maps3d");
构造函数 | |
|---|---|
Map3DElement |
Map3DElement([options])参数：
|
属性 | |
|---|---|
attr: autofits-camera-animation |
默认值：
none用于自动镜头拟合的动画。
HTML 属性： autofits-camera-animation="value-name" |
bounds |
设置后，会将镜头位置限制在指定的纬度/经度边界内。请注意，边界之外的对象仍会渲染。边界可以同时限制经度和纬度，也可以仅限制纬度或经度。对于仅限纬度的边界，请分别使用 -180 和 180 的西经和东经。对于仅限经度的边界，请分别使用 90 和 -90 的北纬和南纬。 |
cameraPosition
attr: camera-position |
以 LatLngAltitude 形式给出的相机位置。如果省略，则会派生。如果省略
center 但指定了 cameraPosition，则 center 将派生自 cameraPosition.。如果两者在同一运行循环中更新，则 cameraPosition 将优先。在给定共享航向、范围、横滚和俯仰的情况下，字段 cameraPosition 和 center 可以相互一对一派生。HTML 属性： camera-position="lat,lng,altitude" |
center
attr: center |
以 LatLngAltitude 形式给出的地图中心，其中海拔高度以平均海平面以上的米数为单位。请注意，这不一定是镜头所在的位置，因为
range 字段会影响镜头与地图中心的距离。如果未设置，则默认为 {lat: 0, lng: 0, altitude: 63710000}。63710000 米是允许的最大高度（地球半径乘以 10）。HTML 属性： center="lat,lng,altitude" |
attr: color-scheme |
指定地图的配色方案。如果未设置，则默认为
ColorScheme.FOLLOW_SYSTEM。HTML 属性： color-scheme="value-name" |
defaultUIHidden
attr: default-ui-hidden |
输入类型：
boolean optional输出类型： boolean默认值：
false如果为
true，则所有默认界面按钮都会隐藏。HTML 属性： default-ui-hidden |
description
attr: description |
输入类型：
string optional输出类型： string optional如果提供了无障碍功能说明（例如，用于屏幕阅读器），则会使用提供的值将该说明添加到地图中。
HTML 属性： description="string" |
fov
attr: fov |
输入类型：
number optional输出类型： number optional指定垂直视野范围（以度为单位）。有效值介于 5.0 到 80.0 之间。值越高，可见区域越大，但可能会导致透视失真。默认值：35.0。
HTML 属性： fov="number" |
gestureHandling
attr: gesture-handling |
控制协作手势处理。如果设置为
COOPERATIVE，则需要使用辅助键或双指手势才能滚动地图。如果设置为 GREEDY，则无法通过地图元素上的用户事件滚动宿主页面。如果设置为 AUTO，手势处理方式将由托管页面的可滚动性决定。HTML 属性： gesture-handling="value-name" |
heading
attr: heading |
输入类型：
number optional输出类型： number optional地图的罗盘航向角（以度为单位），其中正北为零。如果没有倾斜，任何横滚都会被解读为航向。
HTML 属性： heading="number" |
internalUsageAttributionIds
attr: internal-usage-attribution-ids |
向初始化程序添加使用情况归因 ID，这有助于 Google 了解哪些库和示例对开发者有帮助，例如标记聚类器库的使用情况。如需选择不发送使用情况归因 ID，您可以安全地删除此属性。系统只会发送唯一值。实例化后对此值所做的更改可能会被忽略。
HTML 属性： internal-usage-attribution-ids="id1 id2" |
language |
输入类型：
string optional输出类型： string optional尝试呈现基本地图语言时所用的语言。默认情况下，系统会使用开发者在加载 Maps JS API 时请求的语言。 |
mapId
attr: map-id |
输入类型：
string optional输出类型： string optional指定一个地图 ID，用于为地图提取云端地图样式设置。
HTML 属性： map-id="string" |
maxAltitude
attr: max-altitude |
输入类型：
number optional输出类型： number optional地图上将显示的最大海拔高度。有效值介于
0 米和 63710000 米（地球半径乘以 10）之间。HTML 属性： max-altitude="number" |
maxHeading
attr: max-heading |
输入类型：
number optional输出类型： number optional地图的最大朝向（旋转）角度。有效值介于
0 度和 360 度之间。minHeading 和 maxHeading 表示允许进行航向手势操作的区间（<= 360 度）。minHeading = 180 和 maxHeading = 90 将允许在 [0, 90] 中使用标题，在 [180, 360] 中使用标题。minHeading = 90 和 maxHeading = 180 将允许在 [90, 180] 中使用标题。HTML 属性： max-heading="number" |
attr: max-memory-megabytes |
输入类型：
number optional输出类型： number optional地图可用于渲染的最大内存量（以兆字节为单位）。较低的值会减少内存用量，但会牺牲视觉细节；较高的值则允许在内存中保留更多细节。有效值介于 64 到 2048 之间。如果未设置，系统会根据设备和地图大小自动选择限制。必须在地图初始化之前设置；之后所做的更改会被忽略。
HTML 属性： max-memory-megabytes="number" |
maxTilt
attr: max-tilt |
输入类型：
number optional输出类型： number optional地图的最大入射角。有效值介于
0 度和 90 度之间。HTML 属性： max-tilt="number" |
minAltitude
attr: min-altitude |
输入类型：
number optional输出类型： number optional地图上显示的最低海拔高度。有效值介于
0 米和 63710000 米（地球半径乘以 10）之间。HTML 属性： min-altitude="number" |
minHeading
attr: min-heading |
输入类型：
number optional输出类型： number optional地图的最小航向角（旋转角度）。有效值介于
0 度和 360 度之间。minHeading 和 maxHeading 表示允许进行航向手势操作的区间（<= 360 度）。minHeading = 180 和 maxHeading = 90 将允许在 [0, 90] 中使用标题，在 [180, 360] 中使用标题。minHeading = 90 和 maxHeading = 180 将允许在 [90, 180] 中使用标题。HTML 属性： min-heading="number" |
minTilt
attr: min-tilt |
输入类型：
number optional输出类型： number optional地图的最小入射角。有效值介于
0 度和 90 度之间。HTML 属性： min-tilt="number" |
mode
attr: mode |
指定地图的呈现模式。如果未设置，则不会呈现地图。
HTML 属性： mode="value-name" |
attr: quality-mode |
指定地图的渲染质量。设置为
QualityMode.PERFORMANCE 可在渲染时减少视觉细节，从而降低内存用量。HTML 属性： quality-mode="value-name" |
range
attr: range |
输入类型：
number optional输出类型： number optional从镜头到地图中心的距离（以米为单位）。
HTML 属性： range="number" |
region |
输入类型：
string optional输出类型： string optional尝试渲染基本地图的地图注点时所用的区域。默认情况下，系统会使用开发者在加载 Maps JS API 时请求的区域。 |
roll
attr: roll |
输入类型：
number optional输出类型： number optional相机围绕视图矢量的滚转角，以度为单位。为消除歧义，在没有倾斜的情况下，任何横滚都会被解读为航向。
HTML 属性： roll="number" |
tilt
attr: tilt |
输入类型：
number optional输出类型： number optional摄像头视图矢量的倾斜度（以度为单位）。直视地球的视图向量的倾斜度为 0 度。背离地球的视图矢量的倾斜度为
180 度。HTML 属性： tilt="number" |
attr: default-ui-disabled |
类型：
boolean optional默认值：
false如果为
true，则所有默认界面按钮都会停用。不会停用键盘和手势控制。HTML 属性： default-ui-disabled |
方法 | |
|---|---|
flyCameraAround |
flyCameraAround(options)参数：
返回值：无
此方法可让镜头在指定时长内围绕指定位置旋转。动画可以重复指定的 FlyAroundAnimationOptions.repeatCount 次。摄像头将顺时针移动。 环绕的位置通过 CameraOptions.center 指定。这是在环绕动画期间，镜头围绕其移动时，将显示在视口中心的位置。该方法是异步的，因为只有在地图加载了最少内容后，动画才能开始。动画启动后，该方法会返回。 如果 FlyAroundAnimationOptions.repeatCount 次数为零，则不会发生旋转，动画会在开始后立即完成。 |
flyCameraTo |
flyCameraTo(options)参数：
返回值：无
此方法会在指定时长内，将镜头以抛物线轨迹从当前位置移动到指定结束位置。您可以通过 CameraOptions.cameraPosition（控制确切的镜头位置）或 CameraOptions.center（控制地图的可见视口中心）指定结束位置。该方法是异步的，因为只有在地图加载了最少内容后，动画才能开始。动画启动后，该方法会返回。 |
stopCameraAnimation |
stopCameraAnimation()参数：无
返回值：无
此方法会停止可能正在运行的任何飞行效果动画。相机停留在动画中间的任何位置；它不会传送到终点。 该方法是异步的，因为只有在地图加载了最少量的元素后，动画才能开始或停止。动画停止后，该方法会返回。 |
继承的方法：
addEventListener、removeEventListener
| |
事件 | |
|---|---|
gmp-animationend |
function(animationEndEvent)参数：
此事件会在飞行动画结束时触发。此事件会通过 DOM 树向上冒泡。 |
gmp-camerapositionchange |
function(cameraPositionChangeEvent)参数：
当 Map3DElement 的 cameraPosition 属性发生变化时，会触发此事件。 |
gmp-centerchange |
function(centerChangeEvent)参数：
当 Map3DElement 的 center 属性发生变化时，会触发此事件。 |
gmp-click |
function(clickEvent)参数：
当用户点击 Map3DElement 元素时，系统会触发此事件。 |
gmp-error |
function(mapInitializationErrorEvent)参数：
此事件会在地图初始化失败时触发。 |
gmp-fovchange |
function(fovChangeEvent)参数：
当 Map3DElement 的 fov 属性发生变化时，会触发此事件。 |
gmp-headingchange |
function(headingChangeEvent)参数：
当 Map3DElement 的 heading 属性发生变化时，会触发此事件。 |
gmp-map-id-error |
function(mapIdErrorEvent)参数：
当 Map3DElement 的 mapId 属性无效时，会触发此事件。 |
gmp-rangechange |
function(rangeChangeEvent)参数：
当 Map3DElement 的 range 属性发生变化时，会触发此事件。 |
gmp-rollchange |
function(rollChangeEvent)参数：
当 Map3DElement 的 roll 属性发生变化时，会触发此事件。 |
gmp-steadychange |
function(steadyChangeEvent)参数：
当 Map3DElement 的稳定状态发生变化时，会触发此事件。 |
gmp-tiltchange |
function(tiltChangeEvent)参数：
当 Map3DElement 的倾斜度属性发生变化时，会触发此事件。 |
Map3DElementOptions 接口
接口
google.maps.maps3d.Map3DElementOptions
由 Map3DElement 实现
Map3DElementOptions 对象，用于定义可在 Map3DElement 上设置的属性。
MapMode 常量
常量
google.maps.maps3d.MapMode
库 "maps3d"
指定地图的渲染模式。
这些常量也可以用作字符串。在 TypeScript 中，字符串字面量由 MapModeString 类型定义。
const {MapMode} = await google.maps.importLibrary("maps3d");
常量 | |
|---|---|
HYBRID |
此地图模式会在卫星图像或真实感图像上显示一个透明的主要街道图层。 |
|
此地图模式会显示普通街道地图。 |
SATELLITE |
此地图模式会显示卫星图像或仿真图像（如有）。 |
QualityMode 常量
常量
google.maps.maps3d.QualityMode
库 "maps3d"
指定 3D 地图的渲染质量。
这些常量也可以用作字符串。在 TypeScript 中，字符串字面量由 QualityModeString 类型定义。
const {QualityMode} = await google.maps.importLibrary("maps3d");
常量 | |
|---|---|
FIDELITY |
以标准视觉细节渲染地图。 |
PERFORMANCE |
渲染地图时减少视觉细节，以降低内存用量。在内存受限的设备上，或者当地图与占用大量内存的其他内容共享页面时，此功能非常有用。 |
GestureHandling 常量
常量
google.maps.maps3d.GestureHandling
库 "maps3d"
指定应如何在地图元素上处理手势事件。
这些常量也可以用作字符串。在 TypeScript 中，字符串字面量由 GestureHandlingString 类型定义。
const {GestureHandling} = await google.maps.importLibrary("maps3d");
常量 | |
|---|---|
AUTO |
这样，地图便可选择是使用协作式还是贪婪式手势处理。如果未指定，则这是默认行为。 如果地图占据了其滚动父级（通常是宿主页面）的大部分空间，导致用户无法从地图滚动到其他内容，则会导致地图进入协作模式。 |
COOPERATIVE |
这会强制进入合作模式，在该模式下，需要使用辅助键或双指手势才能滚动地图。 |
GREEDY |
这会强制启用贪婪模式，在这种模式下，用户在地图元素上执行的操作无法滚动宿主页面。 |
AutofitsCameraAnimation 常量
常量
google.maps.maps3d.AutofitsCameraAnimation
库 "maps3d"
指定相机在移动到新位置以根据其选择启用的子元素居中时应如何运作。
这些常量也可以用作字符串。在 TypeScript 中，字符串字面量由 AutofitsCameraAnimationString 类型定义。
const {AutofitsCameraAnimation} = await google.maps.importLibrary("maps3d");
常量 | |
|---|---|
FLY_TO |
飞到新位置。 |
NONE |
不使用动画，直接贴靠到新位置。 |
FlyAroundAnimationOptions 接口
接口
google.maps.maps3d.FlyAroundAnimationOptions
FlyCameraAround 动画的自定义选项。
属性 | |
|---|---|
camera |
相机在轨道动画期间应看向的中心点。请注意，地图朝向会随着镜头围绕此中心点旋转而发生变化。 |
durationMillis
可选 |
类型：
number optional一个动画周期的时长（以毫秒为单位）。 |
repeatCount
可选 |
类型：
number optional指定动画应重复的次数。如果该数字为零，动画将在开始后立即完成。如果传入 Number.Infinity，动画将无限重复。 |
可选 |
类型：
number optional在指定时长内围绕中心旋转的圈数。此设置用于控制整体旋转速度。向 rounds 传递负数会导致镜头逆时针旋转，而不是默认的顺时针旋转。 |
FlyToAnimationOptions 接口
接口
google.maps.maps3d.FlyToAnimationOptions
FlyCameraTo 动画的自定义选项。
属性 | |
|---|---|
endCamera |
相机在动画结束时应指向的位置。 |
durationMillis
可选 |
类型：
number optional动画的时长（以毫秒为单位）。如果时长为 0，镜头将直接跳转到结束位置。 |
CameraOptions 接口
接口
google.maps.maps3d.CameraOptions
CameraOptions 对象，用于定义可在相机对象上设置的属性。镜头对象可以是具有镜头位置的任何对象，例如当前地图状态或未来请求的动画状态。
属性 | |
|---|---|
altitudeMode
可选 |
类型：
AltitudeMode optional一个枚举，用于指定如何解读给定 CameraOptions 对象的高度值。这会重复使用现有的 AltitudeMode 枚举。 |
cameraPosition
可选 |
类型：
LatLngAltitude|LatLngAltitudeLiteral|LatLngLiteral optional |
center
可选 |
类型：
LatLngAltitude|LatLngAltitudeLiteral|LatLngLiteral optional请参阅 Map3DElement.center。 |
fov
可选 |
类型：
number optional请参阅 Map3DElement.fov。 |
heading
可选 |
类型：
number optional请参阅 Map3DElement.heading。 |
range
可选 |
类型：
number optional请参阅 Map3DElement.range。 |
roll
可选 |
类型：
number optional请参阅 Map3DElement.roll。 |
tilt
可选 |
类型：
number optional请参阅 Map3DElement.tilt。 |
SteadyChangeEvent 类
class
google.maps.maps3d.SteadyChangeEvent
extends Event
library "maps3d"
此事件是通过监控 Map3DElement 的稳定状态而创建的。此事件会通过 DOM 树向上冒泡。
const {SteadyChangeEvent} = await google.maps.importLibrary("maps3d");
属性 | |
|---|---|
isSteady |
类型：
boolean指明 Map3DElement 是否稳定（即当前场景的所有渲染是否已完成）。 |
LocationClickEvent 类
类
google.maps.maps3d.LocationClickEvent
扩展 Event
由 PlaceClickEvent 扩展
库 "maps3d"
此事件是通过点击 Map3DElement 创建的。
const {LocationClickEvent} = await google.maps.importLibrary("maps3d");
属性 | |
|---|---|
position |
类型：
LatLngAltitude optional事件发生时位于光标下方的纬度/经度/海拔。请注意，在较粗略的级别，系统返回的数据准确性较低。此外，从较高的相机位置点击水面时，系统可能会返回海底海拔高度作为海拔高度值。此事件会通过 DOM 树向上冒泡。 |
LocationPointerEvent 类
class
google.maps.maps3d.LocationPointerEvent
extends Event
library "maps3d"
当在交互式 Map3DElement 上发生指针互动时，系统会创建此事件。
const {LocationPointerEvent} = await google.maps.importLibrary("maps3d");
属性 | |
|---|---|
position |
类型：
LatLngAltitude optional事件发生时位于光标下方的纬度/经度/海拔。请注意，在较粗略的级别，系统返回的数据准确性较低。此外，从较高的相机位置点击水面时，系统可能会返回海底海拔高度作为海拔高度值。此事件会通过 DOM 树向上冒泡。 |
PlaceClickEvent 类
class
google.maps.maps3d.PlaceClickEvent
extends LocationClickEvent, Event
library "maps3d"
此事件是在点击 Map3DElement 上的地点图标时创建的。如需阻止显示默认弹出式窗口，请对此事件调用 preventDefault() 方法，以防止其由 Map3DElement 处理。
const {PlaceClickEvent} = await google.maps.importLibrary("maps3d");
属性 | |
|---|---|
placeId |
类型：
string地图项的地点 ID。 |
继承：
position
| |
方法 | |
|---|---|
fetchPlace |
fetchPlace()参数：无
提取此地点 ID 的 Place。在生成的 Place 对象中，系统会填充 id 属性。随后，您可以通过 Place.fetchFields() 请求其他字段，但需遵守正常的 Places API 启用和结算流程。如果提取 Place 时出错，则 promise 会被拒绝。 |