Ajustar automaticamente a câmera aos elementos do mapa

É possível enquadrar automaticamente marcadores, polilinhas, polígonos e rotas em 3D em uma janela de visualização <gmp-map-3d> definindo o atributo HTML autofits-camera ou a propriedade autofitsCamera em elementos filhos compatíveis. Quando um ou mais elementos filhos são ativados, o mapa calcula uma posição de câmera que mantém todos os elementos ativados visíveis.

O ajuste automático da câmera está disponível no canal v=beta da API Maps JavaScript. Para instruções sobre como carregar o canal Beta, consulte Controle de versões.

Elementos compatíveis

A tabela a seguir lista os elementos filhos de Map3DElement que são compatíveis com autofits-camera (autofitsCamera):

Elemento HTML Classe JavaScript Biblioteca Observações
<gmp-marker-3d>, <gmp-marker-3d-interactive> Marker3DElement, Marker3DInteractiveElement maps3d Enquadra o position do marcador.
<gmp-marker>, <gmp-marker-interactive> MarkerElement, MarkerInteractiveElement maps3d Enquadra o position do marcador.
<gmp-polyline-3d>, <gmp-polyline-3d-interactive> Polyline3DElement, Polyline3DInteractiveElement maps3d Enquadra todas as coordenadas no path da polilinha.
<gmp-polygon-3d>, <gmp-polygon-3d-interactive> Polygon3DElement, Polygon3DInteractiveElement maps3d Enquadra todas as coordenadas no path do polígono.
<gmp-route-3d> Route3DElement routes Aguarda a resolução da solicitação de trajeto e, em seguida, enquadra o caminho do trajeto.

Elementos incompatíveis

Model3DElement, PopoverElement e FlattenerElement não são compatíveis com autofitsCamera. Para enquadrar esses elementos, defina center e range em <gmp-map-3d> ou chame flyCameraTo.

Ajustar a câmera no carregamento inicial

Para enquadrar elementos quando o mapa é carregado, adicione o atributo autofits-camera a cada elemento filho que você quer dentro da janela de visualização inicial. Não é necessário calcular center ou range em <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>

Substitua YOUR_API_KEY pela sua chave de API da Plataforma Google Maps.

Ajustar e animar atualizações dinâmicas

Quando você adiciona um elemento ativado após o carregamento inicial, atualiza as coordenadas ou os endpoints de trajeto dele ou define autofitsCamera como true, o mapa recalcula a câmera para enquadrar todos os elementos ativados. Remover um elemento ou definir autofitsCamera como false deixa a câmera na posição atual e exclui esse elemento de atualizações futuras.

Para controlar se as atualizações dinâmicas são ajustadas ou animadas, defina autofitsCameraAnimation (autofits-camera-animation) em Map3DElement como um valor AutofitsCameraAnimation:

  • AutofitsCameraAnimation.NONE ("none", padrão): ajusta para a posição atualizada sem animação.
  • AutofitsCameraAnimation.FLY_TO ("fly-to"): voa suavemente para a posição atualizada. O carregamento inicial do mapa é feito sem animação, e o FLY_TO volta a um ajuste quando o sistema operacional do usuário solicita uma redução de movimento.

Para configurar autofitsCamera e AutofitsCameraAnimation.FLY_TO de forma programática, consulte o exemplo a seguir:

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

Substitua YOUR_API_KEY pela sua chave de API da Plataforma Google Maps.

Como as propriedades e restrições da câmera interagem

Quando pelo menos um elemento filho ativa o autofits-camera, o Map3DElement combina a configuração do mapa com os limites calculados de acordo com as seguintes regras:

  • center e range: substituídos pelo enquadramento calculado, que adiciona um padding de 20% ao intervalo e aplica um intervalo mínimo de 80 m. Se nenhum elemento filho ativado fornecer coordenadas, o mapa vai usar os valores center e range configurados como substitutos.
  • tilt e heading: tratados como valores sugeridos durante o framing. Quando omitidos, ambos assumem como padrão 0° para uma visualização de cima para baixo, com o norte para cima.
  • roll e fov: preservados conforme configurado em Map3DElement.
  • Elementos filhos assíncronos: antes de renderizar a visualização inicial, Map3DElement aguarda que os elementos filhos assíncronos, como <gmp-route-3d>, terminem de carregar a geometria do trajeto.
  • Restrições de mapa e câmera: os limites geográficos de bounds e da câmera (minAltitude, maxAltitude, minTilt, maxTilt, minHeading e maxHeading) ainda restringem a visualização de ajuste automático. Para mais informações, consulte Restringir a visualização e os limites da câmera.

Próximas etapas