目录

Map Kit手工转换指导书

转换前须知

[h2]开发准备

[h2]gradle配置文件

[h2]switch-case到if-else转化

工具转化完成后，某些使用switch-case选择语句会出现“case expressions must be constant expression”，switch中case必须为常量异常。此类方法需要转化成if-else形式，以此方式解决switch异常问题。

原代码示例：

switch (reason) {
    //REASON_GESTURE:手势
    case OnCameraMoveStartedListener.REASON_GESTURE:
        currPolylineOptions.color(Color.BLUE);
        reasonText = "GESTURE";
        break;
    //REASON_API_ANIMATION:api动画
    case OnCameraMoveStartedListener.REASON_API_ANIMATION:
        currPolylineOptions.color(Color.RED);
        reasonText = "API_ANIMATION";
        break;
    //REASON_DEVELOPER_ANIMATION:开发者动画
    case OnCameraMoveStartedListener.REASON_DEVELOPER_ANIMATION:
        currPolylineOptions.color(Color.GREEN);
        reasonText = "DEVELOPER_ANIMATION";
        break;
}

修改后代码示例：

if (OnCameraMoveStartedListener.getREASON_GESTURE() == reason) {
    this.currPolylineOptions.color(Color.BLUE);
    reasonText = "GESTURE";
} else if (OnCameraMoveStartedListener.getREASON_API_ANIMATION() == reason) {
    this.currPolylineOptions.color(Color.RED);
    reasonText = "API_ANIMATION";
} else if (OnCameraMoveStartedListener.getREASON_DEVELOPER_ANIMATION() == reason) {
    this.currPolylineOptions.color(Color.GREEN);
    reasonText = "DEVELOPER_ANIMATION";
} else {
    reasonText = "UNKNOWN_REASON";
}

fragment

工具Add HMS API转换完成后，对于使用fragment展示的activity，我们提供配置ClassLoader（简单，仅需导入资源和修改配置文件）和手写代码（复杂，手工转换工作量大）两种手工转换方式来实现兼容Google API和HMS。

目前ClassLoader方案暂时不支持用户工程使用插件化或者热修复框架，不支持用户自定义ClassLoader，若您的应用存在上述情况，请使用手写代码方案。

更多关于ClassLoader方案的原理介绍，请参见XClassLoader方案基本原理介绍。

[h2]配置ClassLoader方式

目前ClassLoader方式暂时不支持“Library”模式下的Add HMS API转换，在使用工具转换时请选择“App”模式。

自动转换完后请先在“Conversion”中处理好所有文件中Dummy状态相关接口的手工转换。

  1. 修改工程相关配置文件。
    1. 若勾选了“Generate code for creating app dependent only on GMS SDK”模式，并且启用了单“xmsg”风味变体，请在项目级目录下的settings.gradle文件里修改引用配置如下。
      include ':xmsadapter:xmsaux', 'xmsadapter:xmsaux:xg', 'xmsadapter:xmsaux:xapi'
      若勾选了“Generate code for creating app dependent only on HMS SDK”模式，并且启用了单“xmsh”风味变体，请在项目级目录下的settings.gradle文件里修改引用配置如下。
      include ':xmsadapter:xmsaux', 'xmsadapter:xmsaux:xh', 'xmsadapter:xmsaux:xapi'
      若勾选了以上任一模式，并且启用了单“xmsgh”风味变体，请在项目级目录下的settings.gradle文件里修改引用配置如下。
      include ':xmsadapter:xmsaux', 'xmsadapter:xmsaux:xg', 'xmsadapter:xmsaux:xh', 'xmsadapter:xmsaux:xapi'

      代码风味变体详情请参见Convertor工具实现生成多种变体APK。

    2. 在项目级目录下的build.gradle文件dependencies{}区块中，配置gradle插件版本为3.5.0以上。
      buildscript {
    dependencies {
        classpath 'com.android.tools.build:gradle:3.5.0'
    }
}
    3. 在项目级目录下的gradle/wrapper/gradle-wrapper.properties文件里，配置gradle版本为5.4.1以上。
      distributionUrl=https\://services.gradle.org/distributions/gradle-5.4.1-all.zip
    4. 对于多Module项目工程，需要在项目级目录下的gradle.properties文件里添加如下配置。
      android.enableD8=false
android.enableD8.desugaring=false
  2. 在程序入口处调用init方法初始化。
    1. 在app主应用中实现一个程序入口类继承android.app.Application，并覆写其中onCreate方法。
      public class MyApp extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        GlobalEnvSetting.init(this,null);
        XLoader.init(this);
    }
}
    2. 修改app应用级目录下的src/main/AndroidManifest.xml中应用包名属性application name，添加第一条中新增的application子类。
      <application
    android:name=".MyApp"
</application>
  3. 异常规避。
    1. 如果重新扫描分析工程中出现如下Merge提示信息，请先备份并移除xmsadapter文件夹下的xh、xg和xmsaux文件夹，待扫描分析完成以后，再将备份恢复至xmsadapter目录下。

    1. 为了您的应用安全，我们对打包进APK中assets目录下的xg.apk和xh.apk资源文件有安全校验功能。若在运行时遇到“Apk File is corrupted”报错，说明上述资源文件被篡改或者破坏，请在打包APK之前clean并重新rebuild整个工程。

    2. 如果您的应用在低版本的安卓手机上运行时遇到如下报错信息：

      请在app/build.gradle添加如下配置信息：

      android {
    defaultConfig {
        multiDexEnabled false
    }
}

[h2]手写代码方式

  1. 修改layout资源文件。

    Add HMS API场景下，Google API和HMS需要使用独立的layout资源文件，在各自的资源文件中<fragment/>class路径不同。

    HMS layout资源文件中Fragment定义参考：

    <fragment
     android:id="@+id/map"
     android:layout_width="match_parent"
     android:layout_height="match_parent"
     class="com.huawei.hms.maps.SupportMapFragment" />

    Google API layout资源文件中Fragment定义参考：

    <fragment
     android:id="@+id/map"
     android:layout_width="match_parent"
     android:layout_height="match_parent"
     class="com.google.android.gms.maps.SupportMapFragment" />
    资源文件参考：
    • basic_demo：原始layout资源文件。
    • basic_demo_hms：HMS的layout资源文件。

    layout资源文件都需要一式两份，HMS和Google API各一份，配合代码兼容跳转使用。

  1. 修改代码。

    如果使用到了Fragment，可以在activity的onCreate()方法中通过if-else的方式一份代码同时兼容HMS和Google API。修改方式如下：

    原代码示例：
    protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    //设置gms资源文件
    setContentView(R.layout.events_demo);
    mTapTextView = (TextView) findViewById(R.id.tap_text);
    mCameraTextView = (TextView) findViewById(R.id.camera_text);
    //在Activity的onCreate()方法中加载SupportMapFragment
    SupportMapFragment mapFragment =
             (SupportMapFragment) getSupportFragmentManager().findFragmentById(R.id.map);
    //调用getMapAsync()来注册回调
    mapFragment.getMapAsync(this);
}

    修改后代码示例：

    protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    //根据当前类型，选择根据G或者H创建
    if (org.xms.g.utils.GlobalEnvSetting.isHms()) {
        createAsH();
    } else {
        createAsG();
    }
}
/**
  * HMS 创建流程
  */
private void createAsH() {
    Log.d(TAG, "create as hms");
    //设置hms资源文件
    setContentView(R.layout.events_demo_hms);
    //初始化参数
    initMember();
    //根据id获取hms的fragment
    com.huawei.hms.maps.SupportMapFragment hMapFragment =
             (com.huawei.hms.maps.SupportMapFragment) this.getSupportFragmentManager().findFragmentById(R.id.map);
    //地图加载
    hMapFragment.getMapAsync(this.getHInstanceOnMapReadyCallback());
}
/**
  * GMS 创建流程
  */
private void createAsG() {
    Log.d(TAG, "create as gms");
    //设置gms资源文件
    setContentView(R.layout.events_demo);
    //初始化参数
    initMember();
    //根据id获取gms的fragment
    com.google.android.gms.maps.SupportMapFragment gMapFragment =
             (com.google.android.gms.maps.SupportMapFragment) this.getSupportFragmentManager()
                     .findFragmentById(R.id.map);
    //地图加载
    gMapFragment.getMapAsync(this.getGInstanceOnMapReadyCallback());
}
/**
  * 成员变量初始化，抽离成单独方法
  */
private void initMember() {
    this.mTapTextView = (TextView) findViewById(R.id.tap_text);
    this.mCameraTextView = (TextView) findViewById(R.id.camera_text);
}
    根据当前环境变量中isHms标识，选择Google API或者HMS加载地图资源，方法含义如下：
    • void initMember() ：私有成员变量及可共用代码初始化位置。
    • void createAsG() ：Google API创建流程。
    • void createAsH() ：HMS创建流程。

Map相关常量

工具完成转换后，如果发现在常量引用上有异常，可参考下方列表。googleMap中对常量采用直接使用的方式，但在Add HMS API场景下，常量使用Getter的方式来使用。如：

BitmapDescriptorFactory.HUE_ORANGE ，新的方式采用BitmapDescriptorFactory.getHUE_ORANGE()，Getter的方式来获取。

googleMap常量获取

Add HMS API常量获取

import static com.google.android.gms.maps.GoogleMap.MAP_TYPE_HYBRID（引用后直接使用）

ExtensionMap.getMAP_TYPE_NORMAL()

BitmapDescriptorFactory.HUE_ORANGE

BitmapDescriptorFactory.getHUE_ORANGE()

HuaweiMap.OnCameraMoveStartedListener.REASON_API_ANIMATION

HuaweiMap.OnCameraMoveStartedListener.getREASON_API_ANIMATION()

googleMap常量获取

To HMS API常量获取

import static com.google.android.gms.maps.GoogleMap.MAP_TYPE_HYBRID（引用后直接使用）

import static com.huawei.hms.maps.HuaweiMap.MAP_TYPE_HYBRID（引用后直接使用）

fragment的特殊场景（OnMapAndViewReadyListener）

Marker等部分Demo实现了OnMapAndViewReadyListener.OnGlobalLayoutAndMapReadyListener接口。其使用的Fragment支持Add HMS API场景的转换，在OnMapAndViewReadyListener类中进行，修改参考如下。

streetViewPanoramaFragment

Add HMS API场景下，streeViewPanoramaFragment相对fragment的fragment在调用方式上略微有些不同，但基本思想都是根据系统类型做if-else处理。具体参考如下。

activity中onCreate修改示例。

原代码示例：

protected void onCreate(final Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.street_view_panorama_basic_demo);
    SupportStreetViewPanoramaFragment streetViewPanoramaFragment =
             (SupportStreetViewPanoramaFragment)
                     getSupportFragmentManager().findFragmentById(R.id.streetviewpanorama);
    //设置一个回调对象，该对象将在GoogleMap实例准备好使用时被触发
    streetViewPanoramaFragment.getStreetViewPanoramaAsync(
        new OnStreetViewPanoramaReadyCallback() {
            //当街景全景图准备好使用时调用
            @Override
            public void onStreetViewPanoramaReady(StreetViewPanorama panorama) {
                // Only set the panorama to SYDNEY on startup (when no panoramas have been
                // loaded which is when the savedInstanceState is null).
                if (savedInstanceState == null) {
                    panorama.setPosition(SYDNEY);
                }
            }
        });
}
修改后代码示例：
@Override
protected void onCreate(final Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    if (org.xms.g.utils.GlobalEnvSetting.isHms()) {
        createAsH(savedInstanceState);
    } else {
        createAsG(savedInstanceState);
    }
}
private void createAsH(final Bundle savedInstanceState) {
    Log.d(TAG, "create as hms");
    setContentView(R.layout.street_view_panorama_basic_demo_hms);
    initMember();
    com.huawei.hms.maps.SupportStreetViewPanoramaFragment hStreetViewPanoramaFragment =
             (com.huawei.hms.maps.SupportStreetViewPanoramaFragment) getSupportFragmentManager().findFragmentById(R.id.streetviewpanorama);
    hStreetViewPanoramaFragment.getStreetViewPanoramaAsync(panorama -> {
        // Only set the panorama to SYDNEY on startup (when no panoramas have been
        // loaded which is when the savedInstanceState is null).
        // HMS 转成org.xms
        org.xms.g.maps.StreetViewPanorama xmsStreetViewPanorama =
                 new org.xms.g.maps.StreetViewPanorama(null, panorama);
        if (savedInstanceState == null) {
            xmsStreetViewPanorama.setPosition(SYDNEY);
        }
    });
}
private void createAsG(final Bundle savedInstanceState) {
    Log.d(TAG, "create as gms");
    setContentView(R.layout.street_view_panorama_basic_demo);
    initMember();
    com.google.android.gms.maps.SupportStreetViewPanoramaFragment gStreetViewPanoramaFragment =
             (com.google.android.gms.maps.SupportStreetViewPanoramaFragment) getSupportFragmentManager().findFragmentById(R.id.streetviewpanorama);
    gStreetViewPanoramaFragment.getStreetViewPanoramaAsync(panorama -> {
        // Only set the panorama to SYDNEY on startup (when no panoramas have been
        // loaded which is when the savedInstanceState is null).
        // HMS 转成org.xms
        org.xms.g.maps.StreetViewPanorama xmsStreetViewPanorama =
                 new org.xms.g.maps.StreetViewPanorama(panorama, null);
        if (savedInstanceState == null) {
            xmsStreetViewPanorama.setPosition(SYDNEY);
        }
    });
}
private void initMember() {
 }

streeViewPanoramaFragment的调用可以参考示例修改做业务的对应调整。

部分废弃接口替代方案

如果To HMS API场景使用Location Kit的接口，需要增加Location依赖。版本号“${version”请参见Location Kit的版本更新说明。

implementation 'com.huawei.hms:location:${version}'

如果使用Location功能，需要确保当前已获得位置权限。

获取位置权限示例代码：

/**
* only have permission of location，location function is enable
**/
if(enableMyLocation()){
    getMyLocation();
    setOnMyLocationChangeListener();
}
 /**
* Request code for location permission request.
*
* @see #onRequestPermissionsResult(int, String[], int[])
*/
private static final int LOCATION_PERMISSION_REQUEST_CODE = 1;
/**
* Enables the My Location layer if the fine location permission has been granted.
*/
private boolean enableMyLocation() {
    //动态申请ACCESS_FINE_LOCATION权限
    if (ContextCompat.checkSelfPermission(this,
            Manifest.permission.ACCESS_FINE_LOCATION) != PackageManager.PERMISSION_GRANTED) {
        // Permission to access the location is missing.
        PermissionUtils.requestPermission(this, LOCATION_PERMISSION_REQUEST_CODE,
                Manifest.permission.ACCESS_FINE_LOCATION, true);
        return false;
    }else {
        return true;
    }
}

[h2]HuaweiMap.getMyLocation()

此接口可以使用Location Kit中的FusedLocationProviderClient.getLastLocation()方法替代。关于此接口的详细功能描述，可以参见Location Kit的FusedLocationProviderClient中getLastLocation()方法。

To HMS API示例代码：

// Current position.
private  android.location.Location myLocation;
/**
* this is an Example:
* using location kit getLastLocation ,replace HuaweiMap.getMylocation() function
*/
private void getMyLocation(){
    //调用getLastLocation()方法获取最后的已知位置
    com.huawei.hmf.tasks.Task<android.location.Location> locationTask =  LocationServices
            .getFusedLocationProviderClient(this).getLastLocation();
    //请求位置更新接口完成监听回调
    locationTask.addOnCompleteListener(param0 -> {
        if (locationTask != null) {
            //获取经纬度
            myLocation = locationTask.getResult();
            double Lat = myLocation.getLatitude();
            double Lng = myLocation.getLongitude();
            Log.d(TAG, " Lat is : " + Lat +", Lng is : "+Lng);
        }// 检查设备定位设置接口失败监听回调
    }).addOnFailureListener(param0 -> Log.d(TAG,"lastLocation is error"));
}

Add HMS API示例代码：

//current location
private  android.location.Location myLocation;
/**
* this is an Example:
* using location kit getLastLocation ,replace HuaweiMap.getMylocation() function
*/
private void getMyLocation(){
    //调用getLastLocation()方法获取最后的已知位置
    org.xms.g.tasks.Task<android.location.Location> locationTask =  LocationServices
           .getFusedLocationProviderClient(this).getLastLocation();
    //请求位置更新接口完成监听回调
    locationTask.addOnCompleteListener(param0 -> {
        if (locationTask != null) {
            //获取经纬度
            myLocation = locationTask.getResult();
            double Lat = myLocation.getLatitude();
            double Lng = myLocation.getLongitude();
            Log.d(TAG, " Lat is : " + Lat +", Lng is : "+Lng);
        }// 检查设备定位设置接口失败监听回调
    }).addOnFailureListener(param0 -> Log.d(TAG,"lastLocation is error"));
}

[h2]HuaweiMap.setOnMyLocationListener()

此接口可以使用Location Kit中的FusedLocationProviderClient.requestLocationUpdates(LocationRequest request, LocationCallback callback, Looper looper)方法替代。接口描述请参见FusedLocationProviderClient。

To HMS API示例代码：

/**
* this is an Example
* using location kit requestLocationUpdates(Request,LocationCallback,Looper) ,replace HuaweiMap.setOnMyLocationChangeListener()
*/
private void setOnMyLocationChangeListener(){
    // When you construct request parameters, please refer to the development guide of the Location Kit.
    //设置持续定位请求参数
    com.huawei.hms.location.LocationRequest request = new  com.huawei.hms.location.LocationRequest();
    //设置位置更新的时间（单位为毫秒）
    request.setInterval(2000);
    //调用requestLocationUpdates()进行持续定位
    LocationServices
           .getFusedLocationProviderClient(this).requestLocationUpdates(request, new LocationCallback() {
        @Override
        public void onLocationResult(  com.huawei.hms.location.LocationResult locationResult) {
            if (locationResult != null) {
                //处理位置回调结果
                List<Location> locations = locationResult.getLocations();
                if (!locations.isEmpty()) {
                    for (Location location : locations) {
                        Log.i(TAG,
                                "onLocationResult location[Longitude,Latitude,Accuracy]:"
                                        + location.getLongitude() + "," + location.getLatitude() + ","
                                        + location.getAccuracy());
                    }
                }
            }
        }
        @Override
        public void onLocationAvailability(LocationAvailability locationAvailability) {
            if (locationAvailability != null) {
                //定位是否可用
                boolean flag = locationAvailability.isLocationAvailable();
                Log.i(TAG, "onLocationAvailability isLocationAvailable:" + flag);
            }
        }
    }, android.os.Looper.myLooper()).addOnSuccessListener(new OnSuccessListener<Void>() {
        @Override
        public void onSuccess(Void param0) {
            Log.d(TAG,"onSuccess.....");
        }
    });
}

Add HMS API示例代码：

/**
* this is an Example
* using location kit requestLocationUpdates(Request,LocationCallback,Looper) ,replace HuaweiMap.setOnMyLocationChangeListener()
*/
private void setOnMyLocationChangeListener(){
    //Construct request param，you can read location kit developer guide for details
    org.xms.g.location.LocationRequest request = new  org.xms.g.location.LocationRequest();
     /设置位置更新的间隔（单位为毫秒）
    request.setInterval(2000);
    //调用requestLocationUpdates()进行持续定位
    LocationServices
            .getFusedLocationProviderClient(this).requestLocationUpdates(request, new LocationCallback() {
        @Override
        public void onLocationResult(  org.xms.g.location.LocationResult locationResult) {
            if (locationResult != null) {
                // 处理位置回调结果
                List<Location> locations = locationResult.getLocations();
                if (!locations.isEmpty()) {
                    for (Location location : locations) {
                        Log.i(TAG,
                                "onLocationResult location[Longitude,Latitude,Accuracy]:"
                                        + location.getLongitude() + "," + location.getLatitude() + ","
                                        + location.getAccuracy());
                    }
                }
            }
        }
        @Override
        public void onLocationAvailability(LocationAvailability locationAvailability) {
            if (locationAvailability != null) {
                //定位是否可用
                boolean flag = locationAvailability.isLocationAvailable();
                Log.i(TAG, "onLocationAvailability isLocationAvailable:" + flag);
            }
        }
    }, android.os.Looper.myLooper()).addOnSuccessListener(new OnSuccessListener<Void>() {
        @Override
        public void onSuccess(Void param0) {
            Log.d(TAG,"onSuccess.....");
        }
    });
}

[h2]HuaweiMap.setOnCameraChangeListener()

此方法可以使用setOnCameraMoveStartedListener、setOnCameraMoveListener、setOnCameraIdleListener方法替代，实现moveCamera事件的监听。

示例代码：

/**
* this is an Example
* using setOnCameraMoveStartedListener、setOnCameraMoveListener、setOnCameraIdleListener to
* replace to HuaweiMap.setOnCameraChangeListener.
*/
private void setOnCameraChangeListener() {
    Log.d(TAG, " start addMoveListener...");
    //设置一个回调，当摄像机开始移动时调用
    this.mMap.setOnCameraMoveStartedListener(i -> Log.d(TAG," start camera move..."));
    //设置在摄像机处于运动状态时反复调用的回调函数
    this.mMap.setOnCameraMoveListener(() -> Log.d(TAG," camera moving..."));
    //设置相机移动结束时调用的回调
    this.mMap.setOnCameraIdleListener(() -> {
        Log.d(TAG," idle camera move... ");
    });
}

地图样式功能setMapStyle()

地图样式设置（包括retro、night、grayscale、simple样式 ）需要加载JSON资源文件，HuaweiMap与GoogleMap使用的JSON文件格式上有差异，导致不能共用一份JSON资源文件。需要在业务代码层面做兼容适配。HuaweiMap地图样式JSON文件下载链接。

[h2]To HMS API场景下的修改步骤

  1. 下载huawei json文件。
  2. 在项目中res/raw目录下（即地图样式JSON资源文件目录，各项目可能有所不同），替换同名资源文件内容，替换文件如下图所示。

[h2]Add HMS API场景下的修改步骤

  1. 下载huawei json文件。
  2. 在项目中res/raw目录下（即地图样式JSON资源文件目录，各项目可能有所不同），新增mapstyle_grayscale_hms.json、mapstyle_night_hms.json、mapstyle_retro_hms.json作为HuaweiMap地图样式资源文件，与googleMap地图样式资源文件并存，新增后文件如下图所示。

  3. 修改后Add HMS API兼容示例代码如下。根据系统设置加载不同的JSON资源文件。
    private void setSelectedStyle() {
    MapStyleOptions style;
    switch (this.mSelectedStyleId) {
        case R.string.style_label_retro:
            // Sets the retro style via raw resource JSON.
            if(GlobalEnvSetting.isHms()){
                style = MapStyleOptions.loadRawResourceStyle(this, R.raw.mapstyle_retro_hms);
            }else{
                style = MapStyleOptions.loadRawResourceStyle(this, R.raw.mapstyle_retro);
            }
            break;
        case R.string.style_label_night:
            // Sets the night style via raw resource JSON.
            if(GlobalEnvSetting.isHms()){
                style = MapStyleOptions.loadRawResourceStyle(this, R.raw.mapstyle_night_hms);
            }else{
                style = MapStyleOptions.loadRawResourceStyle(this, R.raw.mapstyle_night);
            }
            break;
        case R.string.style_label_grayscale:
            // Sets the grayscale style via raw resource JSON.
            if(GlobalEnvSetting.isHms()){
                style = MapStyleOptions.loadRawResourceStyle(this, R.raw.mapstyle_grayscale_hms);
            }else{
                style = MapStyleOptions.loadRawResourceStyle(this, R.raw.mapstyle_grayscale);
            }
            break;
        case R.string.style_label_no_pois_no_transit:
            // Sets the no POIs or transit style via JSON string.
            style = new MapStyleOptions("[" + "  {" + "    \"featureType\":\"poi.business\","
                + "    \"elementType\":\"all\"," + "    \"stylers\":[" + "      {"
                + "        \"visibility\":\"off\"" + "      }" + "    ]" + "  }," + "  {"
                + "    \"featureType\":\"transit\"," + "    \"elementType\":\"all\"," + "    \"stylers\":["
                + "      {" + "        \"visibility\":\"off\"" + "      }" + "    ]" + "  }" + "]");
            break;
        case R.string.style_label_default:
            // Removes previously set style, by setting it to null.
            style = null;
            break;
        default:
            return;
    }
    //设置基础地图风格，设置为null表示清除先前的自定义风格
    this.mMap.setMapStyle(style);
}