Google Maps API for Android 指南（一）

概览

Android版Google API 介绍。
通过Android版的Google API，开发者可以基于Google Map的数据开发自己的APP，API将自动连接至Google Map服务器、下载数据、显示呈现以及响应地图手势等。开发者也可以使用API添加标记(markers)、模块(polygons)、覆盖自己的基础地图(overlays to a basic map)、改变视图等。API同样提供了地理信息，方便用户与地图交互，开发者可以使用API添加如下图形：

• 在地图上的具体位置做记号(Icons anchored to specific positions on the map (Markers))；
• 在地图上添加直线或折线(Sets of line segments (Polylines))；
• 在地图上附加模块(Enclosed segments (Polygons))；
• 在具体的位置上锚定位图(Bitmap graphics anchored to specific positions on the map (Ground Overlays))；
• 在基础地图的最上层覆盖一组图像(Sets of images which are displayed on top of the base map tiles (Tile Overlays))；

本文档适合于Android开发者和具有面向对象概念的人阅读。
本文档可以让你对Google Maps Android API 快速入门，你可以参考相关的引用文档，查阅有关类和方法。

使用Google Map API必须要求应用中包含Google Play Services中的法律条款(Legal Notices)。法律条款可以在menu的item项中添加，也可以在“关于”项中添加。
添加法律条款的方法如下：

GoogleApiAvailability.getOpenSourceSoftwareLicenseInfo

Google Maps Android API有不错的兼容性，这种特性可以使任何应用都能使用API。
当在移动设备上使用TalkBack软件时(Talkback是一款由谷歌官方开发的系统工具软件，它的定位是帮助盲人或者有视力障碍的用户提供语言辅助。让盲人或者视力受损的用户可以非常方便的与他们的设备进行有效的互动。当使用Android自带的程序时，Talkback会实时的提供语言反馈)，手指轻扫屏幕，屏幕就会从一个界面切换到另一界面，当另一界面元素获得焦点时，TalkBack会读出该元素。双击屏幕，元素就能获得焦点。

配置一个包含Google Map API的项目

1. 安装Android Studio并打开Android SDK manager，在Extra目录中下载在最新的Android Support Repository和Android Support Library，以及Google Play services。
2. 在创建项目时，选择activity模板时选择“Google Map Activity”，创建的项目中有一个文件叫做google_maps_api.xml，还有一个MapsActivity，其中google_maps_api.xml中用于填写API key。

3. 获取API key：API key是一个字符串，是连接Google servers和开发者应用的桥梁，获取API key有如下三种方式：
   1)、直接复制google_maps_api.xml文件中类似于如下文本的内容到浏览器地址栏（前提是开发者注册了一个Google开发者账号）：
   
   你将获得一个128位的SHA-1编码，该编码就是API key，将API key 复制到google_maps_api.xml文件的相应位置。

   2)、打开网页https://developers.google.com/maps/documentation/android/start#get-key，输入你的key和项目的包名，类似于下列方式： A1:C9:D0:AF:50:B0:4B:45:38:93:F2:AC:1D:E6:E6:D9:FF:78:F1:B6;com.googlemaptest.lenovo.googlemapdemo，通过该方式获得Google map API key。
   3)、参阅下面的网页https://developers.google.com/maps/documentation/android-api/signup#overview。

1. 为布局layout添加如下XML代码：

<fragment xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:id="@+id/map"
    tools:context=".MapsActivity"
    android:name="com.google.android.gms.maps.SupportMapFragment" />

在activity中添加如下代码：

import android.os.Bundle;
import android.support.v4.app.FragmentActivity;
import com.google.android.gms.maps.CameraUpdateFactory;
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;

public class MapsActivity extends FragmentActivity implements OnMapReadyCallback {

    private GoogleMap mMap;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_maps);
        SupportMapFragment mapFragment = (SupportMapFragment) getSupportFragmentManager()
                .findFragmentById(R.id.map);
        mapFragment.getMapAsync(this);
    }

    @Override
    public void onMapReady(GoogleMap googleMap) {
        mMap = googleMap;

        // Add a marker in Sydney, Australia, and move the camera.
        LatLng sydney = new LatLng(-34, 151);
        mMap.addMarker(new MarkerOptions().position(sydney).title("Marker in Sydney"));
        mMap.moveCamera(CameraUpdateFactory.newLatLng(sydney));
    }
}

1. 请确保程序具备以下权限（其中精确位置和粗略位置至少具备其一）

 <!-- 允许程序通过wifi或移动基站的方式获取网络粗略的经纬度信息，定位精度大概误差在30-1500米之内 --> <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/> <!-- 允许程序通过GPS芯片接收卫星的定位信息，定位精度在10米以内 --> <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/> <uses-feature android:name="android.hardware.location.gps"/> <!-- 允许程序获取模拟的定位信息（该权限可省） --> <uses-permission android:name="android.permission.ACCESS_MOCK_LOCATION"/>

1. 连接设备，安装应用，保证设备版本号不低于4.2.2；若使用模拟器，请确保模拟器具备硬件加速功能。

需要注意的是，
1、在AndroidManifest文件中，application标签的子标签中有一个标签，用于填写API key：

<meta-data
    android:name="com.google.android.gms.version"
    android:value="@string/google_maps_key" />

该value所引用的值就是API key，该值应在google_maps_api.xml中配置过：

 <string name="google_maps_key" translatable="false" templateMergeStrategy="preserve">YOUR_KEY_HERE</string>

2、若应用所安装的设备版本是Android 6.0及以上，需要安装的Google play services SDK版本应不低于8.3。
3、以下这两个权限不必开发者手动添加，API会在需要使用这些权限时自动添加：

    <!-- 获取访问网络权限 -->
    <uses-permission android:name="android.permission.INTERNET"/>

    <!-- 允许当前程序获取的网络信息的权限，如，网络是否有效 -->
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

4、同样，Google map需要3D绘制，故需要open GL ES的支持，开发者亦不必手动添加如下声明，API会在需要时自动添加：

<uses-feature  android:glEsVersion="0x00020000" android:required="true"/>

创建地图实例

创建google map实例需要两个重要的类：GoogleMap、MapFragment。
具体代码请参见上小节中的“在activity中添加源码”，其中getMapAsync方法需要运行于主线程中；在onMapReady回调方法中处理GoogleMap对象，当地图可用时，该方法将被回调，并传入一个非空的GoogleMap对象。
一旦GoogleMap对象被实例化，它将自动做如下事情：

• 与google map服务连接；
• 下载地图拼图；
• 将地图拼图显示在设备的屏幕上；
• 显示相关的控制组件，如缩放地图；
• 响应手势操作，如缩放地图。

MapFragment：
MapFragment是Fragment的子类，可将地图以fragment的形式展示在屏幕上，MapFragment实例可被当作是盛放地图的容器，另外，还可通过该类获得GoogleMap实例。
MapView：
MapView是View的子类，该View用于显示google地图，并提供了以个长方形的区域，与MapFragment类似，该类同样用于盛放地图的容器，同时利用该类创建GoogleMap实例。
应使用activity的生命周期回调方法管理GoogleMap实例，如onCreate、onResume、onPause方法等。

地图模式

Google Map提供了五种地图模式：

• Normal（普通）模式：普通的道路地图，可显示人造的景观以及自然景观，比如河流等，道路信息可见。
• Hybrid（混合）模式：普通的道路地图中添加了卫星图像，道路信息可见。
• Satellite（卫星）模式：卫星图像，道路信息不可见。
• Terrain（地形）模式：展示地形数据，地图中包含等高线和透视的阴影，部分道路可见。
• None（空）模式：不显示任何地图图像。
  可以通过GoogleMap的setMapType()方法设置地图模式：

GoogleMap map;
...
// Sets the map type to be "hybrid"
map.setMapType(GoogleMap.MAP_TYPE_HYBRID);

在同一地理位置下，不同的地图模式如下所示：

若将地图模式调成normal或satellite模式，放大地图，地图将展现出更多建筑物的室内信息，如机场、购物商场、大型零售店、加油站等。当缩小地图时，这些建筑的室内信息将被隐藏。如下所示：

通过API设置地图放大时的室内信息：

• 通过GoogleMap.setIndoorEnabled(false)方法可关闭室内信息。默认情况下，室内信息处于开启状态。
• 通过OnIndoorStateChangeListener接口，当一个新的建筑在地图上有焦点时，或某个建筑在被切换放大级别时，该接口中的方法被回调。
• 通过GoogleMap.getFocusedBuilding()方法，可获得当前处于焦点的建筑，通过IndoorBuilding.getActiveLevelIndex()方法获得当前地图的放大级别。

配置地图初始状态

对地图进行初始化配置：

• camera的位置，包括：定位location、放大缩小、方位和倾斜角度；
• 地图的模式；
• 放大按钮或指南正是否显示在屏幕上；
• 手势操作是否可用；
• 轻便模式（lite mode）是否可用，轻便模式可使移动设备在节省内存、和电量的情况下，使用google map最基本的地图功能。

使用XML代码配置属性，（需使用命名空间xmlns:map=”http://schemas.android.com/apk/res-auto”）：

可以在XML代码中为MapFragment和MapView这两个控件配置初始属性：

• mapType属性：设置地图模式；
• cameraTargetLat, cameraTargetLng, cameraZoom, cameraBearing, cameraTilt属性：缩放、经纬度等信息的显示位置；
• uiZoomControls, uiCompass：缩放控件和指南针是否可见；
• uiZoomGestures, uiScrollGestures, uiRotateGestures, uiTiltGestures：相应手势是否可用；
• zOrderOnTop：该属性用于设置Map所在视图是否显示与Z轴的顶部；
• useViewLifecycle：该属性仅对MapFragment有效，该属性表明地图视图是否与fragment的生命周期绑定；
• liteMode：地图是否使用liteMode模式，默认下为false。

为MapFragment配置属性的方式如下（配置MapView的方式与其相同）：

<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"
  map:cameraBearing="112.5"
  map:cameraTargetLat="-33.796923"
  map:cameraTargetLng="150.922433"
  map:cameraTilt="30"
  map:cameraZoom="13"
  map:mapType="normal"
  map:uiCompass="false"
  map:uiRotateGestures="true"
  map:uiScrollGestures="false"
  map:uiTiltGestures="true"
  map:uiZoomControls="false"
  map:uiZoomGestures="true"/>

在代码中动态设置地图属性：
为低筒动态设置属性，需使用GoogleMapOptions对象，具体操作方式如下：

GoogleMapOptions options = new GoogleMapOptions();
options.mapType(GoogleMap.MAP_TYPE_SATELLITE)
    .compassEnabled(false)
    .rotateGesturesEnabled(false)
    .tiltGesturesEnabled(false);

若使用的是MapFragment，则为地图初始化属性的方式为MapFragment.newInstance(GoogleMapOptions options)；
若使用MapView，则方式如下：

MapView(Context, GoogleMapOptions)

地图面板(Map padding)的使用

在使用地图的过程中，尽管用户可以不断变换地图的显示区域，但仍希望一些UI控制按钮（如缩放按钮、指南针、google logo等）能不随地图位置变化，一直显示在屏幕的周围。
通过GoogleMap.setPadding()方法可用于添加地图周围的控制面板，当变换地图的区域时，这些控制面板将缩小而透明；