Cómo agregar un mapa

Selecciona la plataforma: Android iOS JavaScript

En este tema, se describe cómo agregar un mapa básico a una app para Android después de configurar el proyecto para usar el SDK de Maps para Android. Después de agregar un mapa, puedes cambiar el tipo y los componentes.

Descripción general

El SDK de Maps para Android proporciona varias clases que tu app puede usar para administrar el ciclo de vida, la funcionalidad y los datos de un mapa. Las clases admiten interacciones de los usuarios según el modelo de IU de Android, como configurar el estado inicial del mapa y responder a la entrada de gestos de los usuarios en el tiempo de ejecución.

A continuación, se incluyen la interfaz y las clases principales para controlar los mapas:

  • GoogleMap: Es el punto de entrada para administrar los componentes y los datos del mapa subyacente. Tu app solo puede acceder a un objeto GoogleMap si este se recupera desde un objeto SupportMapFragment o MapView.

  • SupportMapFragment: Es un fragmento que permite administrar el ciclo de vida de un objeto GoogleMap.

  • MapView: Es una vista que permite administrar el ciclo de vida de un objeto GoogleMap.

  • OnMapReadyCallback: Es una interfaz de devolución de llamada que controla los eventos y las interacciones de los usuarios del objeto GoogleMap.

Un objeto GoogleMap realiza estas operaciones automáticamente:

  • Conexión al servicio de Google Maps
  • Descarga de mosaicos de mapa
  • Visualización de mosaicos en la pantalla del dispositivo
  • Visualización de varios controles, como el desplazamiento lateral y el zoom
  • Respuesta a gestos de desplazamiento lateral y zoom a través del movimiento del mapa y su acercamiento o alejamiento

Para utilizar un objeto GoogleMap en tu app, debes usar un objeto SupportMapFragment o MapView como contenedor del mapa, y luego recuperar el objeto GoogleMap del contenedor. Dado que las clases de contenedor se derivan de un fragmento o una vista de Android, proporcionan al mapa las funciones de IU y administración del ciclo de vida de sus clases base de Android. La clase SupportMapFragment es el contenedor más común y moderno para un objeto GoogleMap.

Consulta el código

El siguiente código corresponde a la actividad completa de Java que se utiliza en este tema cuando se agrega un fragmento de forma estática. El proyecto de Android se creó a partir de la plantilla Proyecto vacío y, luego, se actualizó según la guía Cómo configurar un proyecto. Una vez que completes los pasos de este tema, tu código puede variar según la plantilla del proyecto.

  package com.example.mapsetup;

  import androidx.appcompat.app.AppCompatActivity;

  import android.os.Bundle;

  import com.google.android.gms.maps.GoogleMap;
  import com.google.android.gms.maps.OnMapReadyCallback;
  import com.google.android.gms.maps.SupportMapFragment;
  import com.google.android.gms.maps.model.LatLng;
  import com.google.android.gms.maps.model.MarkerOptions;

  // Implement OnMapReadyCallback.
  public class MainActivity extends AppCompatActivity implements OnMapReadyCallback {

      @Override
      protected void onCreate(Bundle savedInstanceState) {
          super.onCreate(savedInstanceState);
          // Set the layout file as the content view.
          setContentView(R.layout.activity_main);

          // Get a handle to the fragment and register the callback.
          SupportMapFragment mapFragment = (SupportMapFragment) getSupportFragmentManager()
                  .findFragmentById(R.id.map);
          mapFragment.getMapAsync(this);

      }

      // Get a handle to the GoogleMap object and display marker.
      @Override
      public void onMapReady(GoogleMap googleMap) {
          googleMap.addMarker(new MarkerOptions()
                  .position(new LatLng(0, 0))
                  .title("Marker"));
      }
  }

Cómo agregar un mapa

En esta sección, se describe cómo agregar un mapa básico usando un fragmento como contenedor de mapa. No obstante, también puedes usar una vista. Para ver un ejemplo, consulta RawMapViewDemoActivity en GitHub.

Estos son los pasos básicos:

  1. Para acceder al SDK, obtener una clave de API y agregar los frameworks necesarios, sigue los pasos que figuran en estas secciones:

    1. Configuración en la consola de Google Cloud

    2. Cómo usar una clave de API

    3. Cómo configurar un proyecto de Android Studio

  2. Agrega un objeto SupportMapFragment a la actividad que controlará el mapa. Puedes agregar el fragmento de forma estática o dinámica.

  3. Implementa la interfaz OnMapReadyCallback.

  4. Establece el archivo de diseño como la vista de contenido.

  5. Si agregaste el fragmento de forma estática, obtén un handle para este.

  6. Registra la devolución de llamada.

  7. Obtén un handle para el objeto GoogleMap.

Cómo agregar un objeto SupportMapFragment

Puedes agregar un objeto SupportMapFragment a la app de forma estática o dinámica. La manera más sencilla es hacerlo de manera estática. No obstante, si agregas el fragmento de forma dinámica, podrás realizar acciones adicionales, como quitarlo y reemplazarlo durante el tiempo de ejecución.

Cómo agregar un fragmento de forma estática

En el archivo de diseño de la actividad que controlará el mapa, sigue estos pasos:

  1. Agrega un elemento fragment.
  2. Agrega la declaración de nombre xmlns:map="http://schemas.android.com/apk/res-auto". Esto habilita el uso de atributos XML personalizados de maps.
  3. En el elemento fragment, configura el atributo android:name como com.google.android.gms.maps.SupportMapFragment.
  4. En el elemento fragment, agrega el atributo android:id y configúralo en el ID de recurso R.id.map (@+id/map).

Por ejemplo, aquí te mostramos un archivo de diseño completo que incluye un elemento fragment:

<?xml version="1.0" encoding="utf-8"?>
<fragment xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:map="http://schemas.android.com/apk/res-auto"
    android:name="com.google.android.gms.maps.SupportMapFragment"
    android:id="@+id/map"
    android:layout_width="match_parent"
    android:layout_height="match_parent"/>

Cómo agregar un fragmento de forma dinámica

En la actividad:

  1. Crea una instancia de SupportMapFragment.
  2. Confirma una transacción que agregue el fragmento a la actividad. Para obtener más información, consulta Transacciones de fragmentos.

Por ejemplo:

Java


SupportMapFragment mapFragment = SupportMapFragment.newInstance();
getSupportFragmentManager()
    .beginTransaction()
    .add(R.id.my_container, mapFragment)
    .commit();

Kotlin


val mapFragment = SupportMapFragment.newInstance()
supportFragmentManager
    .beginTransaction()
    .add(R.id.my_container, mapFragment)
    .commit()

Cómo implementar la interfaz OnMapReadyCallback

Actualiza la declaración de actividad de la siguiente manera:

Java


class MainActivity extends AppCompatActivity implements OnMapReadyCallback {
    // ...
}

Kotlin


class MainActivity : AppCompatActivity(), OnMapReadyCallback {

    // ...
}

Cómo configurar la vista de contenido

En el método onCreate de tu actividad, llama al método setContentView y configura el archivo de diseño como la vista de contenido.

Por ejemplo, si el nombre del archivo de diseño es main.xml, el código se verá así:

Java


@Override
protected void onCreate(@Nullable Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.main);
}

Kotlin


override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.main)
}

Cómo obtener un handle para el fragmento y registrar la devolución de llamada

  1. Para obtener un handle para el fragmento, llama al método FragmentManager.findFragmentById y pásale el ID de recurso del fragmento en tu archivo de diseño. Si agregaste el fragmento de forma dinámica, omite este paso porque ya recuperaste el handle.

  2. Llama al método getMapAsync para configurar la devolución de llamada en el fragmento.

Por ejemplo, si agregaste el fragmento de forma estática, el código se verá así:

Java


SupportMapFragment mapFragment = (SupportMapFragment) getSupportFragmentManager()
    .findFragmentById(R.id.map);
mapFragment.getMapAsync(this);

Kotlin


val mapFragment = supportFragmentManager
    .findFragmentById(R.id.map) as SupportMapFragment
mapFragment.getMapAsync(this)

Cómo obtener un handle para el objeto GoogleMap

Utiliza el método de devolución de llamada onMapReady para obtener un handle para el objeto GoogleMap. La devolución de llamada se activa cuando el mapa está listo para recibir entradas del usuario. Proporciona una instancia no nula de la clase GoogleMap que puedes usar para actualizar el mapa.

En este ejemplo, la devolución de llamada onMapReady recupera un handle para el objeto GoogleMap y, luego, se agrega un marcador al mapa:

Java


@Override
public void onMapReady(GoogleMap googleMap) {
    googleMap.addMarker(new MarkerOptions()
        .position(new LatLng(0, 0))
        .title("Marker"));
}

Kotlin


override fun onMapReady(googleMap: GoogleMap) {
    googleMap.addMarker(
        MarkerOptions()
            .position(LatLng(0.0, 0.0))
            .title("Marker")
    )
}

Captura de pantalla con el mapa y el marcador enfocados en Null Island

Cuando compiles y ejecutes la app correctamente, se mostrará un mapa con un marcador en Null Island (latitud y longitud de cero grados).

Consulta el código de la actividad completa:

Ver actividad completa

Próximos pasos

Después de completar estos pasos, puedes configurar los parámetros del mapa.