自动调整镜头以适应地图元素

您可以在支持的子元素上设置 autofits-camera HTML 属性或 autofitsCamera 属性,从而在 <gmp-map-3d> 视口中自动调整标记、多段线、多边形和 3D 路线的框架。当一个或多个子元素选择启用时,地图会计算一个镜头位置,使所有选择启用的元素都保持在视野范围内。

Maps JavaScript API 的 v=beta 渠道中提供了自动镜头调整功能。如需了解如何加载 Beta 渠道,请参阅版本控制。

支持的元素

下表列出了支持 autofits-camera (autofitsCamera) 的 Map3DElement 子元素:

HTML 元素 JavaScript 类 库 备注
<gmp-marker-3d>、<gmp-marker-3d-interactive> Marker3DElement、Marker3DInteractiveElement maps3d 为标记的 position 设定框架。
<gmp-marker>、<gmp-marker-interactive> MarkerElement、MarkerInteractiveElement maps3d 为标记的 position 设定框架。
<gmp-polyline-3d>、<gmp-polyline-3d-interactive> Polyline3DElement、Polyline3DInteractiveElement maps3d 将多段线 path 中的所有坐标纳入视野。
<gmp-polygon-3d>、<gmp-polygon-3d-interactive> Polygon3DElement、Polygon3DInteractiveElement maps3d 框定多边形 path 中的所有坐标。
<gmp-route-3d> Route3DElement routes 等待路线请求解析,然后框定路线路径。

不支持的元素

Model3DElement、PopoverElement 和 FlattenerElement 不支持 autofitsCamera。如需为这些元素设置框架,请在 <gmp-map-3d> 上设置 center 和 range,或调用 flyCameraTo。

在初始加载时调整摄像头

如需在地图加载时框定元素,请向您希望在初始视口中显示的每个子元素添加 autofits-camera 属性。您无需在 <gmp-map-3d> 上计算 center 或 range:

<gmp-map-3d
  style="height: 400px; width: 100%;"
  mode="hybrid">
  <gmp-marker-3d
    position="47.6205,-122.3493"
    title="Space Needle"
    autofits-camera>
  </gmp-marker-3d>
  <gmp-marker-3d
    position="47.6097,-122.3425"
    title="Pike Place Market"
    autofits-camera>
  </gmp-marker-3d>
  <gmp-polyline-3d
    path="47.6205,-122.3493,0 47.6097,-122.3425,0"
    stroke-color="#4285F4"
    stroke-width="8"
    altitude-mode="clamp-to-ground"
    autofits-camera>
  </gmp-polyline-3d>
</gmp-map-3d>

<script async
  src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&v=beta&libraries=maps3d">
</script>

将 YOUR_API_KEY 替换为您的 Google Maps Platform API 密钥。

调整动态更新的大小并为其添加动画效果

在初始加载后,如果您添加了选择启用的元素、更新了其坐标或路线端点,或者将 autofitsCamera 设置为 true,地图会重新计算镜头,以取景所有选择启用的元素。移除元素或将 autofitsCamera 设置为 false 会使摄像头保持在原位,并从未来的更新中排除该元素。

如需控制动态更新是贴靠还是动画,请将 Map3DElement 上的 autofitsCameraAnimation (autofits-camera-animation) 设置为 AutofitsCameraAnimation 值:

  • AutofitsCameraAnimation.NONE("none",默认):不使用动画,直接贴靠到更新后的位置。
  • AutofitsCameraAnimation.FLY_TO ("fly-to"):平稳地飞到更新后的位置。初始地图加载会直接跳转,不带动画;如果用户的操作系统请求减少动画效果,FLY_TO 会回退到直接跳转。

如需以编程方式配置 autofitsCamera 和 AutofitsCameraAnimation.FLY_TO,请参阅以下示例:

<div id="map-container" style="height: 400px; width: 100%;"></div>

<script>
  async function initMap() {
    const {
      AutofitsCameraAnimation,
      Map3DElement,
      Marker3DElement,
      MapMode,
    } = await google.maps.importLibrary('maps3d');

    const map = new Map3DElement({
      mode: MapMode.HYBRID,
      autofitsCameraAnimation: AutofitsCameraAnimation.FLY_TO,
    });
    document.getElementById('map-container').append(map);

    const originMarker = new Marker3DElement({
      position: { lat: 37.7955, lng: -122.3937 },
      autofitsCamera: true,
    });
    map.append(originMarker);

    /* Adding a second opted-in marker flies the camera to frame both. */
    const destinationMarker = new Marker3DElement({
      position: { lat: 37.8080, lng: -122.4177 },
      autofitsCamera: true,
    });
    map.append(destinationMarker);
  }
</script>
<script async
  src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&v=beta&loading=async&callback=initMap">
</script>

将 YOUR_API_KEY 替换为您的 Google Maps Platform API 密钥。

相机属性和限制如何相互作用

当至少一个子元素通过 autofits-camera 选择启用时,Map3DElement 会根据以下规则将您的地图配置与计算出的边界相结合:

  • center 和 range:被计算出的取景范围覆盖,该取景范围会增加 20% 的范围填充,并强制执行 80 米的最小范围。如果没有任何已选择加入的子元素提供坐标,地图会使用其配置的 center 和 range 作为后备。
  • tilt 和 heading:在取景期间被视为建议值。如果省略,则两者都默认为 0°,即上北下南的俯视图。
  • roll 和 fov:按照在 Map3DElement 上的配置保留。
  • 异步子元素:在渲染初始视图之前,Map3DElement 会等待选择启用的异步子元素(例如 <gmp-route-3d>)完成路线几何图形加载。
  • 地图和镜头限制:地理位置 bounds 和镜头限制(minAltitude、maxAltitude、minTilt、maxTilt、minHeading 和 maxHeading)仍会限制自动调整的视图。如需了解详情,请参阅限制镜头视图和边界。

后续步骤