Adatta automaticamente la fotocamera agli elementi della mappa

Puoi inquadrare automaticamente indicatori, polilinee, poligoni e percorsi 3D all'interno di un viewport <gmp-map-3d> impostando l'attributo HTML autofits-camera o la proprietà autofitsCamera sugli elementi secondari supportati. Quando uno o più elementi secondari vengono attivati, la mappa calcola una posizione della fotocamera che mantiene visibili tutti gli elementi attivati.

L'adattamento automatico della videocamera è disponibile nel canale v=beta dell'API Maps JavaScript. Per istruzioni su come caricare il canale beta, consulta Controllo delle versioni.

Elementi supportati

La tabella seguente elenca gli elementi secondari di Map3DElement che supportano autofits-camera (autofitsCamera):

Elemento HTML Classe JavaScript Raccolta Note
<gmp-marker-3d>, <gmp-marker-3d-interactive> Marker3DElement, Marker3DInteractiveElement maps3d Inquadra il position dell'indicatore.
<gmp-marker>, <gmp-marker-interactive> MarkerElement, MarkerInteractiveElement maps3d Inquadra il position dell'indicatore.
<gmp-polyline-3d>, <gmp-polyline-3d-interactive> Polyline3DElement, Polyline3DInteractiveElement maps3d Inquadra tutte le coordinate nel path della polilinea.
<gmp-polygon-3d>, <gmp-polygon-3d-interactive> Polygon3DElement, Polygon3DInteractiveElement maps3d Inquadra tutte le coordinate nel path del poligono.
<gmp-route-3d> Route3DElement routes Attende la risoluzione della richiesta di percorso, quindi inquadra il percorso.

Elementi non supportati

Model3DElement, PopoverElement e FlattenerElement non supportano autofitsCamera. Per inquadrare questi elementi, imposta center e range su <gmp-map-3d> o chiama flyCameraTo.

Adatta la videocamera al caricamento iniziale

Per inquadrare gli elementi quando la mappa viene caricata, aggiungi l'attributo autofits-camera a ogni elemento secondario che vuoi inserire nell'area visibile iniziale. Non è necessario calcolare center o range su <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>

Sostituisci YOUR_API_KEY con la tua chiave API Google Maps Platform.

Adatta e anima gli aggiornamenti dinamici

Quando aggiungi un elemento attivato dopo il caricamento iniziale, aggiorni le sue coordinate o i punti di arrivo del percorso o imposti autofitsCamera su true, la mappa ricalcola la fotocamera per inquadrare tutti gli elementi attivati. Se rimuovi un elemento o imposti autofitsCamera su false, la videocamera rimane nella sua posizione e l'elemento viene escluso dagli aggiornamenti futuri.

Per controllare se gli aggiornamenti dinamici vengono agganciati o animati, imposta autofitsCameraAnimation (autofits-camera-animation) su Map3DElement su un valore AutofitsCameraAnimation:

  • AutofitsCameraAnimation.NONE ("none", predefinito): si aggancia alla posizione aggiornata senza animazione.
  • AutofitsCameraAnimation.FLY_TO ("fly-to"): si sposta in modo fluido alla posizione aggiornata. Il caricamento iniziale della mappa si aggancia senza animazione e FLY_TO torna a un aggancio quando il sistema operativo dell'utente richiede un movimento ridotto.

Per configurare autofitsCamera e AutofitsCameraAnimation.FLY_TO in modo programmatico, consulta l'esempio seguente:

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

Sostituisci YOUR_API_KEY con la tua chiave API Google Maps Platform.

Come interagiscono le proprietà e le limitazioni della videocamera

Quando almeno un elemento secondario attiva autofits-camera, Map3DElement combina la configurazione della mappa con i limiti calcolati in base alle seguenti regole:

  • center e range: vengono sostituiti dall'inquadratura calcolata, che aggiunge un padding dell'intervallo del 20% e applica un intervallo minimo di 80 m. Se nessun elemento secondario attivato fornisce coordinate, la mappa utilizza i valori center e range configurati come valori di riserva.
  • tilt e heading: vengono trattati come valori suggeriti durante l'inquadratura. Se omessi, entrambi i valori vengono impostati su 0° per una visualizzazione dall'alto verso il basso, con il nord in alto.
  • roll e fov: conservati come configurati su Map3DElement.
  • Elementi secondari asincroni: prima di eseguire il rendering della visualizzazione iniziale, Map3DElement attende che gli elementi secondari asincroni attivati, come <gmp-route-3d>, terminino il caricamento della geometria del percorso.
  • Limitazioni della mappa e della fotocamera: i limiti geografici bounds e della fotocamera (minAltitude, maxAltitude, minTilt, maxTilt, minHeading e maxHeading) limitano comunque la visualizzazione con adattamento automatico. Per saperne di più, consulta Limita la visuale e i limiti della videocamera.

Passaggi successivi