Ajuster automatiquement la caméra aux éléments de la carte

Vous pouvez cadrer automatiquement des repères, des polylignes, des polygones et des itinéraires 3D dans un viewport <gmp-map-3d> en définissant l'attribut HTML autofits-camera ou la propriété autofitsCamera sur les éléments enfants compatibles. Lorsqu'un ou plusieurs éléments enfants sont activés, la carte calcule une position de la caméra qui permet de garder tous les éléments activés dans le champ de vision.

L'ajustement automatique de la caméra est disponible dans la version v=beta de l'API Maps JavaScript. Pour savoir comment charger la version bêta, consultez Gestion des versions.

Éléments compatibles

Le tableau suivant liste les éléments enfants de Map3DElement qui sont compatibles avec autofits-camera (autofitsCamera) :

élément HTML Classe JavaScript Bibliothèque Remarques
<gmp-marker-3d>, <gmp-marker-3d-interactive> Marker3DElement, Marker3DInteractiveElement maps3d Cadre le position du repère.
<gmp-marker>, <gmp-marker-interactive> MarkerElement, MarkerInteractiveElement maps3d Cadre le position du repère.
<gmp-polyline-3d>, <gmp-polyline-3d-interactive> Polyline3DElement, Polyline3DInteractiveElement maps3d Encadre toutes les coordonnées dans le path de la polyligne.
<gmp-polygon-3d>, <gmp-polygon-3d-interactive> Polygon3DElement, Polygon3DInteractiveElement maps3d Encadre toutes les coordonnées dans le path du polygone.
<gmp-route-3d> Route3DElement routes Attend que la requête d'itinéraire soit résolue, puis encadre le chemin de l'itinéraire.

Éléments non compatibles

Model3DElement, PopoverElement et FlattenerElement ne sont pas compatibles avec autofitsCamera. Pour cadrer ces éléments, définissez center et range sur <gmp-map-3d> ou appelez flyCameraTo.

Ajuster la caméra lors du chargement initial

Pour cadrer des éléments lors du chargement de la carte, ajoutez l'attribut autofits-camera à chaque élément enfant que vous souhaitez inclure dans la fenêtre d'affichage initiale. Vous n'avez pas besoin de calculer center ou range sur <gmp-map-3d> :

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

Remplacez YOUR_API_KEY par votre clé API Google Maps Platform.

Ajuster et animer les mises à jour dynamiques

Lorsque vous ajoutez un élément activé après le chargement initial, que vous mettez à jour ses coordonnées ou les points de terminaison de l'itinéraire, ou que vous définissez autofitsCamera sur true, la carte recalcule la caméra pour cadrer tous les éléments activés. La suppression d'un élément ou la définition de autofitsCamera sur false laisse la caméra à sa position et exclut cet élément des futures mises à jour.

Pour contrôler si les mises à jour dynamiques s'alignent ou s'animent, définissez autofitsCameraAnimation (autofits-camera-animation) sur Map3DElement sur une valeur AutofitsCameraAnimation :

  • AutofitsCameraAnimation.NONE ("none", par défaut) : s'aligne sur la position mise à jour sans animation.
  • AutofitsCameraAnimation.FLY_TO ("fly-to") : vole de manière fluide vers la position mise à jour. Le chargement initial de la carte s'effectue sans animation, et FLY_TO revient à un chargement sans animation lorsque le système d'exploitation de l'utilisateur demande une réduction des mouvements.

Pour configurer autofitsCamera et AutofitsCameraAnimation.FLY_TO de manière programmatique, consultez l'exemple suivant :

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

Remplacez YOUR_API_KEY par votre clé API Google Maps Platform.

Interaction entre les propriétés et les restrictions de la caméra

Lorsqu'au moins un élément enfant active l'option avec autofits-camera, Map3DElement combine la configuration de votre carte avec les limites calculées selon les règles suivantes :

  • center et range : remplacés par le cadrage calculé, qui ajoute une marge de 20 % et applique une plage minimale de 80 m. Si aucun élément enfant activé ne fournit de coordonnées, la carte utilise les valeurs center et range configurées comme valeurs de remplacement.
  • tilt et heading : traités comme des valeurs suggérées lors du cadrage. En cas d'omission, les deux valeurs sont définies par défaut sur 0° pour une vue plongeante orientée vers le nord.
  • roll et fov : conservés tels qu'ils sont configurés sur Map3DElement.
  • Éléments enfants asynchrones : avant d'afficher la vue initiale, Map3DElement attend que les enfants asynchrones activés, tels que <gmp-route-3d>, aient fini de charger la géométrie de l'itinéraire.
  • Restrictions de carte et de caméra : les limites géographiques (bounds) et de caméra (minAltitude, maxAltitude, minTilt, maxTilt, minHeading et maxHeading) continuent de s'appliquer à la vue ajustée automatiquement. Pour en savoir plus, consultez Limiter la vue et les limites de la caméra.

Étapes suivantes