地图组件-Android 最后更新时间: 2021年01月22日

此文档仅包含地图部分核心功能, 如需查看更详细地图相关文档请查看<高德地图Android接入文档>

基本功能-显示地图

使用地图SDK之前，需要在 AndroidManifest.xml 文件中进行相关权限设置，确保地图功能可以正常使用.

注意：该文档是以 3D 地图 SDK 为示例进行讲解2D 地图 SDK 用户可参考步骤流程框架，具体内容上会存在差异，建议对应官方示例Demo.

第一步，配置AndroidManifest.xml

首先，声明权限

//地图SDK（包含其搜索功能）需要的基础权限
     
<!--允许程序打开网络套接字-->
<uses-permission android:name="android.permission.INTERNET" />
<!--允许程序设置内置sd卡的写权限-->
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />   
<!--允许程序获取网络状态-->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /> 
<!--允许程序访问WiFi网络信息-->
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" /> 
<!--允许程序读写手机状态和身份-->
<uses-permission android:name="android.permission.READ_PHONE_STATE" />     
<!--允许程序访问CellID或WiFi热点来获取粗略的位置-->
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

然后，设置高德Key

在application标签中加入如下内容：

Java

<meta-data android:name="com.amap.api.v2.apikey" android:value="key">
//开发者申请的key  
</meta-data>

点我获取Key.

点我查看Key注册时必要数据SHA1和包名的获取方法.

第二步，向工程中添加地图开发包

向一个Android应用中添加地图，具体步骤如下：

在Eclipse环境下：

步骤1：开发工程中新建“ libs ”文件夹，将地图包（2D或3D）、搜索包拷贝到 libs 的根目录下.若选择3D地图包，还需要将各库文件夹一起拷贝.拷贝完成后的工程目录(以3D V2.2.0为例)如图所示：

在Android Studio环境下：

步骤1：

添加so文件，在src/main/目录下新建jniLibs目录，并将文件放入其中.

方法一：

使用默认配置，不需要修改build.gradle.在 main 目录下创建文件夹 jniLibs (如果有就不需要创建了)，将下载文件的 armeabi 文件夹复制到这个目录下,如果已经有这个目录，将下载的 so 库复制到这个目录即可.如图所示：

方法二：

使用自定义配置，将下载文件的 armeabi 文件夹复制到 libs 目录，如果有这个目录,请将下载的 so 库复制到这个目录，然后打开build.gradle，找到 sourceSets 标签，在里面增加一项配置，如图所示：

步骤2：

将jar包放入libs目录下，对于每个jar文件，右键-选择Add As Library，导入到工程中.或者使用菜单栏选择 File ->Project Structure->Modules-> Dependencies.点击绿色的加号选择File Dependency. 然后选择要添加的jar包即可，此时build.gradle中会自动生成如下信息.

或者直接使用引入libs下所有jar包的方式，如下图所示：

第三步，初始化地图容器

MapView 是 AndroidView 类的一个子类，用于在 Android View 中放置地图. MapView 是地图容器.用 MapView 加载地图的方法与 Android 提供的其他 View 一样，具体的使用步骤如下：

首先在布局xml文件中添加地图控件:

Java


<com.amap.api.maps.MapView

    android:id="@+id/map"

    android:layout_width="match_parent"

    android:layout_height="match_parent"/>

在项目中使用地图的时候需要注意，需要合理的管理地图生命周期，这非常的重要.

以下示例简述地图生命周期的管理：

Java

public class MainActivity extends Activity {
  MapView mMapView = null;
  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState); 
    setContentView(R.layout.activity_main);
    //获取地图控件引用
    mMapView = (MapView) findViewById(R.id.map);
    //在activity执行onCreate时执行mMapView.onCreate(savedInstanceState)，创建地图
    mMapView.onCreate(savedInstanceState);
  }
  @Override
  protected void onDestroy() {
    super.onDestroy();
    //在activity执行onDestroy时执行mMapView.onDestroy()，销毁地图
    mMapView.onDestroy();
  }
 @Override
 protected void onResume() {
    super.onResume();
    //在activity执行onResume时执行mMapView.onResume ()，重新绘制加载地图
    mMapView.onResume();
    }
 @Override
 protected void onPause() {
    super.onPause();
    //在activity执行onPause时执行mMapView.onPause ()，暂停地图的绘制
    mMapView.onPause();
    }
 @Override
 protected void onSaveInstanceState(Bundle outState) {
    super.onSaveInstanceState(outState);
    //在activity执行onSaveInstanceState时执行mMapView.onSaveInstanceState (outState)，保存地图当前的状态
    mMapView.onSaveInstanceState(outState);
  } 
}

常用地图容器

地图 SDK 底层运用两种 OpenGL ES 组件构建地图，分别是 GLSurfaceView 和 TextureView，如果您对本节内容不感兴趣，可直接略过此节阅读第四步.

GLSurfaceView：

包括 MapView、MapFragment、SupportMapFragment 三种容器.

下面简单介绍一下 SupportMapFragment：

MapFragment 是 Android Fragment 类的一个子类，用于在 Android Fragment 中放置地图. MapFragment 也是地图容器，与 MapView 一样提供对 AMap 对象（地图的控制类）的访问权.与 MapView 相比 SupportMapFragment 方便之处在于其可以更好的管理地图的生命周期，布局灵活.

TextureView：

包括TextureMapView、TextureMapFragment、TextureSupportMapFragment 三种容器.

使用场景：您将MapView与其他的GLSurfaceView（比如相机）叠加展示，或者是在ScrollView中加载地图时，建议使用TextureMapView及SupportTextureMapFragment来展示地图，可以有效解决 GLSurfaceView 叠加时出现的穿透、滚动黑屏等问题.篇幅有限，如果您感兴趣的话，以上6种地图容器的构造均可在官方示例代码中找到具体的使用方法.

第四步，显示地图

AMap 类是地图的控制器类，用来操作地图.它所承载的工作包括：地图图层切换（如卫星图、黑夜地图）、改变地图状态（地图旋转角度、俯仰角、中心点坐标和缩放级别）、添加点标记（Marker）、绘制几何图形(Polyline、Polygon、Circle)、各类事件监听(点击、手势等)等，AMap 是地图 SDK 最重要的核心类，诸多操作都依赖它完成.

在 MapView 对象初始化完毕之后，构造 AMap 对象.示例代码如下：

Java

//定义了一个地图view
mapView = (MapView) findViewById(R.id.map);
mapView.onCreate(savedInstanceState);// 此方法须覆写，虚拟机需要在很多情况下保存地图绘制的当前状态。
//初始化地图控制器对象
AMap aMap;
if (aMap == null) {
    aMap = mapView.getMap();        
}

篇幅有限，如果您感兴趣的话，以上6种地图容器初始化 AMap 对象的方式均可在官方示例代码中找到具体的示例.

运行您刚完成的工程就可以在您的 APP 中看到高德地图了.运行后的效果如下图所示：

高级功能

更多高级功能,请查看Android地图SDK:http://lbs.amap.com/api/android-sdk/summary

功能1: 显示乘客定位位置

第一步，初始化 AMap 对象

初始化 AMap 对象内容在显示地图章节中有详细讲解.

第二步，实现定位蓝点

实现定位蓝点：

Java

MyLocationStyle myLocationStyle;
myLocationStyle = new MyLocationStyle();//初始化定位蓝点样式类myLocationStyle.myLocationType(MyLocationStyle.LOCATION_TYPE_LOCATION_ROTATE);//连续定位、且将视角移动到地图中心点，定位点依照设备方向旋转，并且会跟随设备移动。（1秒1次定位）如果不设置myLocationType，默认也会执行此种模式。
myLocationStyle.interval(2000); //设置连续定位模式下的定位间隔，只在连续定位模式下生效，单次定位模式下不会生效。单位为毫秒。
aMap.setMyLocationStyle(myLocationStyle);//设置定位蓝点的Style
//aMap.getUiSettings().setMyLocationButtonEnabled(true);设置默认定位按钮是否显示，非必需设置。
aMap.setMyLocationEnabled(true);// 设置为true表示启动显示定位蓝点，false表示隐藏定位蓝点并不进行定位，默认是false。

定位蓝点展现模式

定位蓝点提供8种模式：

Java

myLocationStyle.myLocationType(MyLocationStyle.LOCATION_TYPE_SHOW);//只定位一次。
myLocationStyle.myLocationType(MyLocationStyle.LOCATION_TYPE_LOCATE) ;//定位一次，且将视角移动到地图中心点。
myLocationStyle.myLocationType(MyLocationStyle.LOCATION_TYPE_FOLLOW) ;//连续定位、且将视角移动到地图中心点，定位蓝点跟随设备移动。（1秒1次定位）
myLocationStyle.myLocationType(MyLocationStyle.LOCATION_TYPE_MAP_ROTATE);//连续定位、且将视角移动到地图中心点，地图依照设备方向旋转，定位点会跟随设备移动。（1秒1次定位）
myLocationStyle.myLocationType(MyLocationStyle.LOCATION_TYPE_LOCATION_ROTATE);//连续定位、且将视角移动到地图中心点，定位点依照设备方向旋转，并且会跟随设备移动。（1秒1次定位）默认执行此种模式。
//以下三种模式从5.1.0版本开始提供
myLocationStyle.myLocationType(MyLocationStyle.LOCATION_TYPE_LOCATION_ROTATE_NO_CENTER);//连续定位、蓝点不会移动到地图中心点，定位点依照设备方向旋转，并且蓝点会跟随设备移动。
myLocationStyle.myLocationType(MyLocationStyle.LOCATION_TYPE_FOLLOW_NO_CENTER);//连续定位、蓝点不会移动到地图中心点，并且蓝点会跟随设备移动。
myLocationStyle.myLocationType(MyLocationStyle.LOCATION_TYPE_MAP_ROTATE_NO_CENTER);//连续定位、蓝点不会移动到地图中心点，地图依照设备方向旋转，并且蓝点会跟随设备移动。

是否显示定位蓝点

控制是否显示定位蓝点

Java

//方法自5.1.0版本后支持
MyLocationStyle showMyLocation(boolean visible)//设置是否显示定位小蓝点，用于满足只想使用定位，不想使用定位小蓝点的场景，设置false以后图面上不再有定位蓝点的概念，但是会持续回调位置信息。

自定义定位蓝点图标：

定位蓝点图标自定义：

Java

MyLocationStyle myLocationIcon(BitmapDescriptor myLocationIcon);//设置定位蓝点的icon图标方法，需要用到BitmapDescriptor类对象作为参数。

自定义定位蓝点图标的锚点：

锚点是指定位蓝点图标像素与定位蓝点坐标的关联点，例如需要将图标的左下方像素点与定位蓝点的经纬度关联在一起，通过如下方法传入（0.0,1.0）.图标左上点为像素原点.

Java

MyLocationStyle anchor(float u, float v);//设置定位蓝点图标的锚点方法。

精度圆圈的自定义：

精度圈颜色自定义方法如下

Java

MyLocationStyle strokeColor(int color);//设置定位蓝点精度圆圈的边框颜色的方法。
MyLocationStyle radiusFillColor(int color);//设置定位蓝点精度圆圈的填充颜色的方法。

精度圈边框宽度自定义方法如下

Java

MyLocationStyle strokeWidth(float width);//设置定位蓝点精度圈的边框宽度的方法。

定位的频次自定义：

定位频次修改只会在定位蓝点的连续定位模式下生效，定位蓝点支持连续定位的模式是：

Java

MyLocationStyle.LOCATION_TYPE_FOLLOW ;//连续定位、且将视角移动到地图中心点，定位蓝点跟随设备移动。（默认1秒1次定位）
MyLocationStyle.LOCATION_TYPE_MAP_ROTATE;//连续定位、且将视角移动到地图中心点，地图依照设备方向旋转，定位点会跟随设备移动。（默认1秒1次定位）
MyLocationStyle.LOCATION_TYPE_LOCATION_ROTATE;//连续定位、且将视角移动到地图中心点，定位点依照设备方向旋转，并且会跟随设备移动。（默认1秒1次定位）默认执行此种模式。

调整定位频次的方法如下：

Java

MyLocationStyle interval(long interval);//设置定位频次方法，单位：毫秒，默认值：1000毫秒，如果传小于1000的任何值将按照1000计算。该方法只会作用在会执行连续定位的工作模式上。

获取经纬度信息：

实现 AMap.OnMyLocationChangeListener 监听器，通过如下回调方法获取经纬度信息：

Java

public void onMyLocationChange(android.location.Location location)｛
   //从location对象中获取经纬度信息，地址描述信息，建议拿到位置之后调用逆地理编码接口获取（获取地址描述数据章节有介绍）
}

功能2:自定义地图

创建样式文件

创建地图样式

高德地图开放平台的开发者在取得开发者账号后，可以进入开发者控制台，在地图自定义平台选择“创建地图样式”，可以选择一个模板进行创建.

编辑地图样式

在创建的页面的左侧列表选择任一要素编辑样式属性；也可以单击地图，在弹出的列表中选择要素进行编辑.

发布地图样式并下载

编辑完成后点击右上角“保存”->“发布”，发布完成后，选择“使用方法”，然后选择“android”平台，点击“下载离线文件”.

设定样式文件

设定离线样式文件

1、将配置好的样式文件放入任意路径，比如”/sdcard/custom_config”（注意：自V5.2.0起，既支持style.json文件，也支持.data文件）

2、设定地图样式文件的路径，通过以下方法设定自定义地图样式文件的绝对路径：

Java

//该方法在AMap类中提供
setCustomMapStylePath("/sdcard/custom_config");

设定在线样式文件（需要在官网购买相关权限）

如果觉得下载样式文件过程比较繁琐，也可以使用在线的方式调用，在自定义平台发布之后会有一份样式ID(如图所示)，并通过SDK的 setCustomMapStyleID 设置。如果需要变动样式，只需要在发布之后重新加载一次地图即可看到效果.

注：如果同时设置了在线样式和离线样式，会优先进行在线拉取，如果拉取失败了会再次读取离线样式；

Java

//该方法在AMap类中提供
setCustomMapStyleID("自定义平台发布后生成的id");

开启自定义样式

设置自定义地图后，自定义地图默认为关闭状态，可通过如下方法开启：

Java

//该方法在AMap类中提供
setMapCustomEnable(Boolean enable);//true 开启; false 关闭

自定义纹理（需要在官网购买相关权限）

第 1 步，自定义平台配置纹理

在自定义平台选择支持纹理配置的属性（如陆地），选择配置纹理，可以选择平台提供的图片，也可以自行上传（注：图片大小为2^n*2^n效果会更好）（目前移动端支持的纹理为陆地、绿地、水系和建筑物）

第 2 步，下载样式文件

在第一步配置完成之后选择发布样式，回来到样式下载页面，参考之前提到的方式下载离线样式文件，下载名称为 mystyle_sdk_xx.zip 解压后结构如下

style.data

textures.zip

第 3 步，设置样式文件

将上一步中两个文件放入移动设备可以读取的地方，如Android的SD卡 /sdcard/custom_config/

1.设置样式配置文件路径

Java

//该方法在AMap类中提供 
setCustomMapStylePath("/sdcard/custom_config/style.data"); setCustomTextureResourcePath("/sdcard/custom_config/textures.zip");

2.开启/关闭自定义样式功能

Java

//该方法在AMap类中提供
 setMapCustomEnable(boolean enable);//true 开启; false 关闭

注：纹理暂不支持在线拉取，如果调用了setCustomMapStyleID也需要将纹理通过setCustomTextureResourcePath设置了才会生效

功能3: 驾车出行路线规划

驾车路径规划可以根据起终点和驾车路线的数据，使用 DrivingRouteOverlay 画出驾车路线图层，包括起终点和转弯点.另外也可以自定义起终点和驾车转弯点的图标.

注意：地图SDK V4.1.3版本开始，SDK不再提供 com.amap.api.maps.overlay 包下的 overlay，已在官方demo中开源.

第 1 步，初始化 RouteSearch 对象

Java


routeSearch = new RouteSearch(this);

第 2 步，设置数据回调监听器

Java

routeSearch.setRouteSearchListener(this);

第 3 步，设置搜索参数

通过 DriveRouteQuery(RouteSearch.FromAndTo fromAndTo, int mode, List<LatLonPoint> passedByPoints, List<List<LatLonPoint>> avoidpolygons, String avoidRoad) 设置搜索条件，方法对应的参数说明如下：

fromAndTo，路径的起点终点；
mode，路径规划的策略，可选，默认为0-速度优先；推荐选择策略10, 详细策略请见驾车策略说明；
passedByPoints，途经点，可选；
avoidpolygons，避让区域，可选，支持32个避让区域，每个区域最多可有16个顶点.如果是四边形则有4个坐标点，如果是五边形则有5个坐标点；
avoidRoad，避让道路，只支持一条避让道路，避让区域和避让道路同时设置，只有避让道路生效.

Java

// fromAndTo包含路径规划的起点和终点，drivingMode表示驾车模式
// 第三个参数表示途经点（最多支持16个），第四个参数表示避让区域（最多支持32个），第五个参数表示避让道路
DriveRouteQuery query = new DriveRouteQuery(fromAndTo, drivingMode, null, null, "");

第 4 步，发送请求

使用类 RouteSearch 的 calculateRideRouteAsyn(RideRouteQuery query) 方法进行骑行规划路径计算.

Java

routeSearch.calculateDriveRouteAsyn(query);

第 5 步，接收数据

在 RouteSearch.OnRouteSearchListener 接口回调方法 void onDriveRouteSearched(DriveRouteResult result, int rCode) 处理驾车规划路径结果.返回的信息中包括：路线的距离、高速费用（仅针对7座以下轿车）、路况情况等等.

说明：

1）可以在回调中解析 result，获取驾车的路径.

2）result.getPaths()可以获取到 DrivePath 列表，驾车路径的详细信息可参考 DrivePath 类.

3）返回结果成功或者失败的响应码.1000为成功，其他为失败（详细信息参见网站开发指南-实用工具-错误码对照表）

Java

public void onDriveRouteSearched(DriveRouteResult result, int rCode) {  
   //解析result获取算路结果，可参考官方demo
}

功能4: 司机端展示热力图

基于车辆和供需预测数据,通过热力图进行展示相关业务数据,为司机端提供运营建议

第1步，组织热力图数据

以下以本地模拟数据为例，简单说明 SDK 热力图需要的是经纬度点数组/列表数据.

示例代码如下：

Java

//生成热力点坐标列表
LatLng[] latlngs = new LatLng[500];
double x = 39.904979;
double y = 116.40964;
 
for (int i = 0; i < 500; i++) {
double x_ = 0;
double y_ = 0;
x_ = Math.random() * 0.5 - 0.25;
y_ = Math.random() * 0.5 - 0.25;
latlngs[i] = new LatLng(x + x_, y + y_);
}

第2步，构建热力图 HeatmapTileProvider

HeatmapTileProvider 是生成热力图的核心类，一些基础用法可参考如下代码：

Java

// 构建热力图 HeatmapTileProvider
HeatmapTileProvider.Builder builder = new HeatmapTileProvider.Builder();
builder.data(Arrays.asList(latlngs)) // 设置热力图绘制的数据
.gradient(ALT_HEATMAP_GRADIENT); // 设置热力图渐变，有默认值 DEFAULT_GRADIENT，可不设置该接口
// Gradient 的设置可见参考手册
// 构造热力图对象
HeatmapTileProvider heatmapTileProvider = builder.build();

第3步，绘制热力图图层

通过 TileOverlay 绘制热力图，方法如下：

Java

// 初始化 TileOverlayOptions
TileOverlayOptions tileOverlayOptions = new TileOverlayOptions();
tileOverlayOptions.tileProvider(heatmapTileProvider); // 设置瓦片图层的提供者 
// 向地图上添加 TileOverlayOptions 类对象
mAMap.addTileOverlay(tileOverlayOptions);

效果图如下：

参考手册

Android地图: 参考手册