快速入门for Eclipse

最后更新时间：2019年5月17日

APP GIS 数据准备

在移动GIS开发应用中，地图数据组织与配置是第一步，非常关键，地图数据制作之后才能进行显示和操作。

MapGIS Mobile 10.3全面支持在线地图和离线地图模式，在线地图实现了和PC端数据服务器的完美对接，支持接入OGC服务、第三方公共地图服务等；离线地图则实现本地移动端地图数据的加载，不需在线GIS服务器的支持（即脱离MapGIS IGServer服务器）。

MapGIS 10.3不仅采用一体化的数据存储管理机制来管理二、三维地图数据，并且以统一的数据组织方式（*.mapx）来支撑移动端GIS应用。不管是在线地图还是离线地图，都可以组织为.mapx格式即地图文档来进行调用，并且这也是最常用的格式。此外，移动端还可以使用纯代码方式直接加载在线服务图层或离线地图，在线方式通过服务图层的方式加载在线服务图层，离线方式直接加载离线数据库中的地图数据或者通过图层方式加载离线瓦片数据。

离线地图：如果要使用离线地图，需先进行数据转换操作，然后再将生成的移动数据包拷贝到移动设备中；
在线地图： 如果要使用在线地图，首先要发布自己的服务并获取服务地址，或者获取已有的服务地址，然后再组织、配置数据。

>>移动端的地图数据组织与配置

说明：在进行移动GIS应用开发前，需要根据应用需求制定应用数据组织方案，即在线地图或离线地图，然后相应准备地图数据并进行配置。

当前入门示例for 2D以离线地图——武汉市的矢量地图文档（wuhan.xml）为例，将此地图文档的整个数据文件一起拷贝到移动端设备（如真机或模拟器）的sdcard根目录下，路径为：/sdcard/MapGIS Demo/map/wuhan/wuhan.xml。即将【MapGIS Demo】文件夹整个数据文件一起拷贝，包含离线数据库文件、地图文档文件、地图基本库（符号库、颜色库、字体库），以确保地图正常显示。

040拷贝离线地图文件.png

创建第一个“Hello World”项目

通过Eclipse的ADT插件创建一个全新的“Hello World”项目，实现一个简单的应用程序，旨在帮助大家初次了解和学习在Eclipse集成环境下的Android开发，从零起步。

新建Android项目

启动打开Eclipse（ADT），通过File -> New-> Android Application Project，弹出创建新项目的对话框，如下图所示，设置基本信息即项目名称（如HelloWorld）、SDK、主题等，然后单击【Next】按钮；

0501EADT新建Android项目.png
0502EADTAndroid项目基本设置.png

注：Application Name即为应用安装到手机后图标下显示的名称；Package Name为包名，为该应用的唯一标识，建议使用单位的反转域名（如com.mapgis）。

Android项目配置

(1) 设置新建项目的存放路径，默认勾选“Create custom launcher icon”创建一个app图标、勾选“Create activity”创建一个Activity，单击【Next】按钮进入下一步；

0503EADT项目路径.png

(2) 若上一步勾选“Create custom launcher icon”项，创建一个app图标，如下图所示，设置新图标样式，然后单击【Next】按钮进入下一步；

0504EADT设置新图标.png

(3) 若前面勾选“Create activity”项，创建一个Activity，如下图所示，选择一个Activity模板，如创建一个空白的Activity，然后单击【Next】按钮进入下一步；

0505EADT创建空白的Activity.png

(4) 若前面勾选“Create activity”项，选择一个Activity模板后需设置Activity名称与主题，如下图所示，然后单击【Finish】按钮即可；

0506EADTActivity设置.png

完成Android项目创建

新项目“HelloWorld”创建完成，如下图所示，默认打开先建项目的布局界面（activity_main.xml）。

0507EADT成功创建项目.png

Eclipse（ADT）工具使用说明：创建新项目后的ADT用户界面如下图所示，其中窗口左侧为项目资源管理器，右侧则为工作区，可以了解Eclipse（ADT）的常用布局与模块功能，逐一查看。

0508EADT的界面布局.png

Android项目工程说明：Android项目下的res目录为资源目录，放置app相关的图片资源、布局文件、系统设置文件等。其中，res/layout目录下为app的布局文件（类似于前台展现页面）；src目录则放置java文件（类似于后台的Model与Control），用于app的业务逻辑处理等。

0509Android项目工程目录.png

项目调试运行

在Eclipse的ADT中开发编写APP后，从工具栏单击【Run】，选择【Run】或【Debug】项进行调试运行；也可以右键单击项目工程选择【Run As】或【Debug As】，然后点击【Android Application】调试运行APP，将APP安装到手机或模拟器中并自动运行。

0510EADT调试运行APP.png
0511手机运行app.png

实现第一个GIS 功能的APP(2D)

基于MapGIS Mobile 10.3 for Android的二次开发库进行GIS移动端应用的二次开发，在创建的Android项目中引用其二次开发库（即Libs目录下的.so与.jar文件），直接调用相关控件和接口实现移动GIS功能。

以实现基本的离线地图显示功能为例，使用Eclipse的ADT开发的具体步骤如下：

新建Android工程

启动Eclipse，参考创建“Hello World”项目的方法，新建一个名为“FirstMap”的项目，即在ADT中通过File -> New-> Android Application Project创建，根据项目应用需要依次进行项目的相关设置。

0512新建map项目1.png
0513新建map项目2.png
0514新建map项目3.png
0515新建map项目4.png
0516新建map项目5.png
0517新建map项目6.png
0518已创建的map项目.png

引用二次开发库

Mobile 10.3 for Android的二次开发库，即将SDK包libs里的所有jar包与so库拷贝配置到新建项目中。

在新建的Android项目中引用MapGIS Mobile 10.3 for Android的二次开发库，可以将SDK包libs里的所有文件直接拷贝到新建项目的libs中，或者通过项目属性中的“Library”依次添加引用所需的二次开发库jar包。

0519拷贝二次开发库.png
0520引用二次开发库.png

设置移动端设备资源使用权限

一般开发APP时，由于APP通常会使用存储卡、网络、相机、定位等资源，因此需要为应用添加移动终端设备资源的使用权限，在AndroidManifest.xml（类似于系统配置文件）中编写对应权限标签。

根据应用的实际需求添加对应的应用程序权限。例如，此程序用于实现地图显示功能，需要进行MapGIS环境初始化、授权操作，加载离线地图，所以需要应用具备读/写手机存储的权限、联网权限、读取手机状态的权限。

<!-- 允许应用程序只读访问手机状态 -->
<uses-permission android:name="android.permission.READ_PHONE_STATE"></uses-permission>
<!-- 允许应用程序读取外部存储数据 -->
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"></uses- permission>
<!-- 允许应用程序向外部存储写入数据，如SD卡上写文件 -->
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"></uses-permission>
<!-- 允许应用程序访问网络，可能产生GPRS流量 -->
<uses-permission android:name="android.permission.INTERNET"></uses-permission>

需注意的是，在应用程序的targetSdkVersion版本大于等于23，手机的Android系统版本大于等于6.0时，对于读写手机存储、读取手机状态等危险权限，需要在Java代码中通过代码来动态申请权限。

环境初始化与授权请求

要使用MapGIS移动平台提供的功能，导入开发库后，还需要初始化MapGIS环境、请求移动端授权，这样GIS功能才能得以使用。移动开发授权功能对应的API程序包为com.zondy.mapgis.android.environment，使用环境类（Environment）的接口方法实现。

具体操作为：展开工程中的src/main/java目录，打开“MainActivity.java”文件，在其中调用Environment类的initialize()方法进行环境初始化，然后调用requestAuthorization()方法请求授权。当程序执行到requestAuthorization方法的回调中即表明已经成功授权。

    //MapGIS环境目录：本地路径
    String strRootPath = android.os.Environment.getExternalStorageDirectory().getPath() + "/MyFirstMap/";
    //环境初始化，必须在使用SDK各组件之前调用，会自动建立根目录结构
    com.zondy.mapgis.android.environment.Environment.initialize(strRootPath,this);
    //请求授权
    com.zondy.mapgis.android.environment.Environment.requestAuthorization(this, new Environment.AuthorizeCallback() {
        @Override
        public void onComplete() {
            System.out.println("授权完成");
        }
    });

代码说明：调用initialize()进行环境初始化，必须在使用SDK各组件之前调用，会自动建立根目录结构。

新增地图控件并编码实现地图显示

（1）页面布局（res/layout/activity_main.xml）——加载地图控件

在工程中展开res/layout目录，打开activitymain.xml文件，初始化加载一个MapView视图（com.zondy.mapgis.android.mapview.MapView）并设置其ID，即在activitymain.xml文件中新增加载MapView视图的代码。

0521加载一个MapView视图.png

<com.zondy.mapgis.android.mapview.MapView
    android:id="@+id/mapView"
    android:layout_width="match_parent"
    android:layout_height="match_parent">
</com.zondy.mapgis.android.mapview.MapView>

代码解析：地图控件（com.zondy.mapgis.android.mapview.MapView），作为一个地图容器，用于装载显示地图，可通过其ID获得此地图容器对象。

（2）代码编写（src下的MainActivity.java文件）——地图控件中加载地图数据

在工程中展开src的目录，打开MainActivity.java文件，先获取移动设备SD卡上放置地图数据文件的路径，进行环境初始化，然后调用云授权请求的接口，在其回调中通过地图视图对象调用loadFromFile接口加载离线地图。

0522加载离线地图代码.png

    private MapView mapView;              //定义地图视图对象
    mapView=findViewById(R.id.mapView);    //实例化地图视图对象
    //加载地图文档（离线地图文档路径）
    mapView.loadFromFile(android.os.Environment.getExternalStorageDirectory().getPath() + "/MyFirstMap/WuHan.mapx");

代码解析：在MainActivity.java的onCreate方法中编写加载地图的具体实现代码，主要接口为loadFromFile，此为加载地图的统一接口，不管加载离线地图还是在线地图，均调用此接口实现，参数为地图文件的路径。

调试运行APP

将项目安装到模拟器或者手机上，并运行。右键单击“FirstMap”|“Run As”|“Android Application”，如下图所示，即可将项目安装到移动设备（或模拟器）上，并显示运行之后的界面。

0523调试运行app.png

提示：若初次运行基于MapGIS Mobile 10.3开发的app，将在app中弹出对话框进行授权认证，许可认证后的移动端设备再次运行使用此app则不会再弹框认证。

在外部模拟器（Droid4X）运行app，确保地图数据已经拷贝到模拟器的SD卡目录下，初次运行时弹出对话框进行授权认证，许可认证成功后进入地图显示界面。

0524外部模拟器运行app1.png
0525外部模拟器运行app2.png

在手机上运行app，确保地图数据已经拷贝到手机的SD卡目录下，初次运行时弹出对话框进行授权认证，许可认证成功后进入地图显示界面。

0526手机上运行app的地图显示效果.png

至此，第一个基于MapGIS Mobile 10.3的地图显示的Android App开发完毕。

实现第一个GIS 功能的APP(3D)

实现3D功能的GIS APP应用，与实现2D功能的步骤相似，前4个步骤（新建Android工程、引用二次开发库、设置移动端设备资源使用权限、环境初始化与授权请求）完全一样，可直接参考。接下来讲解后续不相同的步骤。

新增场景控件并编码实现地图显示

（1）页面布局（res/layout/activity _ main.xml）——加载地图控件

在工程中展开res/layout目录，打开activity _ main.xml文件，初始化加载一个SceneView视图（com.zondy.mapgis.android.sceneview.SceneView）并设置其ID，即在activity_main.xml文件中新增加载SceneView视图的代码。

加载一个SceneView视图.png

<com.zondy.mapgis.android.sceneview.SceneView
    android:id="@+id/sceneView"
    android:layout_width="match_parent"
    android:layout_height="match_parent">
</com.zondy.mapgis.android.sceneview.SceneView>

代码解析：场景控件（com.zondy.mapgis.android.sceneview.SceneView），作为一个容器，用于装载显示三维场景，可通过其ID获得此场景容器对象。

（2）代码编写（src下的MainActivity.java文件）——地图控件中加载地图数据

在工程中展开src的目录，打开MainActivity.java文件，先获取移动设备SD卡上放置地图数据文件的路径，进行环境初始化，然后调用云授权请求的接口，在其回调中通过加载三维场景。

加载离线三维场景代码.png

//定义场景视图、场景
private SceneView sceneView;
private Scene scene;

//实例化三维矢量图层
VectorLayer3D mVectorLayer3D = new VectorLayer3D();
//为图层设置名称
mVectorLayer3D.setName("离线矢量数据");
//为图层设置驱动类型（OGR数据驱动.用于离线矢量数据的读取）
mVectorLayer3D.setDriverType(DriverType.Driver_Type_OGR);
//为图层设置URL
mVectorLayer3D.setURL(android.os.Environment.getExternalStorageDirectory().getPath() + "/MyFirstScene/" + "Scene/haiyang/haiyang.shp");

//实例化场景、三维矢量图层
scene = new Scene();
//为场景添加图层
scene.addLayer(mVectorLayer3D);

//实例化场景视图对象
sceneView = findViewById(R.id.sceneView);
//设置无光模式
sceneView.setSunLightingMode(SunLightingMode.NONE);
//为场景视图设置场景
sceneView.setSceneAsync(scene, new SceneView.SceneFinishCallback() {
    @Override
    public void onDidFinish(boolean b) {
        if (b) {
            //场景加载成功
        } else {
            //场景加载失败
        }
    }
});

代码解析：在MainActivity.java的onCreate方法中编写加载三维场景的具体实现代码。

调试运行APP

调试运行场景app.png

提示：若初次运行基于MapGIS Mobile 10.3开发的app，将在app中弹出对话框进行授权认证，许可认证后的移动端设备再次运行使用此app则不会再弹框认证。

至此，第一个基于MapGIS Mobile 10.3的三维场景显示的Android App开发完毕。

APP调试运行

编程开发好的APP，可以通过Android模拟器（简称AVD）或真机设备进行调试运行。其中，真机设备包括智能手机、PDA等。在此我们把真机设备认为是一部安装 Android 系统的智能手机，简称手机。下面介绍在Eclipse ADT中模拟器、真机、第三方模拟器上运行程序的操作流程。

方式一：内置模拟器

Android虚拟设备，是一套模拟器配置方案，它允许大家设定出与实际情况相符的Android设备型号，使得开发者可在各种设备平台上运行调试，非常简便。

创建配置模拟器

通过工具栏上的模拟器按钮，打开Eclipse的ADT中的Android Virtual Device Manager界面，可创建管理一个或多个模拟器，如下图所示，根据应用需求配置即可。

0527内置模拟器管理界面.png

运行安装APP

调试运行APP时，可从工具栏单击【Run】，选择【Run】或【Debug】项，将启用默认的模拟器（或选择所需的模拟器）开始运行或者调试活动启动项。

方式二：真机（移动设备）

由于模拟器无法达到100%的真正模拟效果，例如相机、重力感应、横竖屏切换等。另外，若PC机配置不高，使用自带的模拟器来调试应用，可能会导致运行卡顿，无法满足运行调试的需求。此时可以使用真机，即Android终端设备来安装调试。真机的性能较高、速度快，运行之后就是真实的效果，因此在条件满足的情况下使用真机运行可能有更好的效果。

下面介绍在Eclipse ADT环境下如何将Android应用程序安装、运行在一个Android操作系统的真实设备上，以手机为例。

说明：建议初学者使用模拟器运行，在手机上运行需要进行相关设置，即打开手机的USB debugging功能。

连接配置真机环境

手机连接、设置包括如下三个步骤：

（1）连接手机：使用USB线连接手机和你开发项目的PC机，连上之后一般会自动安装驱动（若没有自动安装可借助第三方手机助手或者手动安装对应驱动）。

（2）打开USB调试功能：对于不同Android版本、不同定制Android版本的手机，方法不一样，但是最终目的就是找到USB调试功能并开启：低于Android 4.2版本的手机， “设置->应用程序->USB调试”，或者“设置->开发人员选项->USB调试”开启；Android 4.2及更高版本的手机上，开发者选项默认是隐藏的，先进入“设置”，找到“关于手机”，连续点击“版本号”（英文名Build number）7次，即可开启“开发人员选项”模块，勾选“USB调试”等设置项即可。

（3）设置USB连接方式：开启USB调试之后，设置手机连接电脑的USB模式为能够传输文件的方式即可，如“传输文件”或者“多媒体传输”等。

0435USB调试功能.png

连接安装APP

手机设置完成之后，即可运行安装。方法：在Eclipse的ADT中开发编写APP后，从工具栏单击【Run】，选择【Run】或【Debug】项进行调试运行；也可以右键单击项目工程选择【Run As】或【Debug As】，然后点击【Android Application】调试运行APP，将APP安装到手机中并自动运行。

0528EADT调试运行APP工具菜单.png
0529EADT调试运行APP右键菜单.png

方式三：第三方模拟器

有时Android SDK自带的模拟器性能较低，可能会比较卡顿；或者使用USB连接真机时，有可能会出现无法识别手机或者USB连接不稳定等问题。此时，可以使用第三方模拟器。目前出现了很多优秀的模拟器，例如Genymotion、Droid4X（海马玩）、BlueStacks（蓝叠）、逍遥等等。安装在PC端，可以很好地模拟手机的操作系统、视觉界面、操作习惯，并且运行速度较快、性能稳定，能基本上达到和真实手机接近的体验效果，便于Android开发人员测试程序，应用范围也较广。

在此以Droid4X（海马玩）为例，讲解如何使用第三方模拟器安装、运行Android程序，其他应用类似。

安装配置第三方模拟器

在开发环境中安装第三模拟器如Droid4X，并打开Droid4X模拟器软件，采用竖屏界面，可自行设置界面分辨率。

注：使用外部模拟器运行app时，确保ADT已正确读取识别虚拟模拟器（一般先启动模拟器，后启动ADT）。

0437海马玩模拟器.png

连接安装APP

通过工具栏上的模拟器按钮，打开Eclipse的ADT中的Android Virtual Device Manager界面，可查看已启动的第三方外部虚拟设备，如Droid4X（海马玩模拟器）等。调试运行APP时，可从工具栏单击【Run】，选择【Run】或【Debug】项，选择所需的模拟器开始运行或者调试活动启动项。

0530Droid4X运行app.png

调试运行常用快捷键

调试Android程序的方法与Eclipse中Java开发类似，通过设置断点进行程序调试。常用快捷键如下：

【Ctrl+Shift+B】：在当前行设置断点或取消设置的断点；
【F11】：调试最后一次执行的程序；
【Ctrl+F11】：运行最后一次执行的程序；
【F5】：跟踪到方法中，当程序执行到某方法时，可以按【F5】键跟踪到方法中；
【F6】：单步执行程序；
【F7】：执行完方法，返回到调用此方法的后一条语句；
【F8】：继续执行，到下一个断点或程序结束。