添加地图

本主题介绍了在将项目配置为使用 Maps SDK for Android 后,如何向 Android 应用添加基本地图。添加地图后,您可以更改地图类型和地图项

概览

Maps SDK for Android 提供多个类,可供应用用来管理地图的生命周期、功能和数据。这些类支持基于 Android 界面模型的用户互动,例如设置地图的初始状态以及在运行时响应用户的手势输入。

用于处理地图的主接口和类如下:

  • GoogleMap - 用于管理底层地图项和地图数据的入口点。只有当系统已从 SupportMapFragmentMapView 对象中检索到 GoogleMap 对象后,您的应用才可以访问该对象。

  • SupportMapFragment - 用于管理 GoogleMap 对象生命周期的 fragment

  • MapView - 用于管理 GoogleMap 对象的生命周期的视图

  • OnMapReadyCallback - 用于处理 GoogleMap 对象的事件和用户互动的回调接口。

GoogleMap 对象会自动执行下列操作:

  • 连接到 Google 地图服务。
  • 下载地图图块。
  • 在设备屏幕上显示图块。
  • 显示各种控件,例如平移和缩放控件。
  • 通过移动和缩放地图响应平移和缩放手势。

若要在应用中使用 GoogleMap 对象,您必须先将 SupportMapFragmentMapView 对象用作地图的容器对象,然后再从该容器中检索 GoogleMap 对象。容器类派生自 Android fragment 或视图,因此可为地图提供 Android 基类的生命周期管理和界面功能。SupportMapFragment 类是适用于 GoogleMap 对象的更为现代和常用的容器。

查看代码

下列代码来自于本主题中以静态方式添加 fragment 时所使用的完整 Java activity。相应 Android 项目是使用空项目模板创建,然后按照项目配置指南进行更新的。执行完本主题中的步骤后,您的代码可能会因项目模板而异。

  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"));
      }
  }

添加地图

本部分介绍了如何通过将 fragment 用作地图容器来添加基本地图;不过,您也可以选择使用视图。如需查看示例,请参阅 GitHub 上的 RawMapViewDemoActivity

基本步骤:

  1. 在开始之前:确保您已完成项目配置指南中的步骤,以便将项目设置为使用 Maps SDK for Android。

  2. 向将用于处理地图的 activity 添加 SupportMapFragment 对象。您可以静态方式添加该 fragment,也可以动态方式添加。

  3. 实现 OnMapReadyCallback 接口。

  4. 将布局文件设置为内容视图。

  5. 如果您是以静态方式添加上述 fragment 的,请先获取该 fragment 的句柄。

  6. 注册回调函数。

  7. 获取 GoogleMap 对象的句柄。

添加 SupportMapFragment 对象

您可以静态方式向应用添加 SupportMapFragment 对象,也可以动态方式添加。最简单的方式是以静态方式添加。如果您以动态方式添加,则还可以对该 fragment 执行其他操作,如在运行时移除和替换该 fragment。

以静态方式添加 fragment

在将用于处理地图的 activity 的布局文件中,执行以下操作:

  1. 添加 fragment 元素。
  2. 添加名称声明 xmlns:map="http://schemas.android.com/apk/res-auto"。完成此操作后即可使用 maps 自定义 XML 属性
  3. fragment 元素中,将 android:name 属性设置为 com.google.android.gms.maps.SupportMapFragment
  4. fragment 元素中,添加 android:id 属性并将其设置为 R.id.map 资源 ID (@+id/map)。

例如,以下是一个包含 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"/>

以动态方式添加 fragment

在相应 activity 中:

  1. 创建 SupportMapFragment 实例。
  2. 提交向 activity 添加该 fragment 的事务。如需了解详情,请参阅 fragment 事务

例如:

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

实现 OnMapReadyCallback 接口

按如下所示更新 activity 声明:

Java

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

Kotlin

class MainActivity : AppCompatActivity(), OnMapReadyCallback {

    // ...
}
      

设置内容视图

在您的 activity 的 onCreate 方法中,调用 setContentView 方法,并将布局文件设置为内容视图。

例如(假如布局文件名为 main.xml):

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

获取 fragment 的句柄并注册回调函数

  1. 若要获取相应 fragment 的句柄,请调用 FragmentManager.findFragmentById 方法,并向其传递布局文件中的 fragment 的资源 ID。如果您是以动态方式添加该 fragment 的,请跳过此步骤,因为您已经检索了句柄。

  2. 调用 getMapAsync 方法,在 fragment 上设置回调。

例如(假如您是以静态方式添加 fragment 的):

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)
      

获取 GoogleMap 对象的句柄

使用 onMapReady 回调方法获取 GoogleMap 对象的句柄。该回调将在地图准备好接收用户输入时触发。它会提供 GoogleMap 类的非空实例,可供您用来更新地图。

在以下示例中,onMapReady 回调会检索 GoogleMap 对象的句柄,然后系统会向地图添加标记

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")
    )
}
      


地图的屏幕截图,在中心位置的空虚岛上有一个标记。

当您成功构建并运行应用后,它会显示一个地图,并在空虚岛(经度 0 度,纬度 0 度)上显示一个标记。

查看完整 activity 的代码:

查看完整 activity


后续操作

完成上述步骤后,您就可以配置地图设置了。