开发 地图 JS API 2.0 升级指南

升级指南 最后更新时间: 2023年04月04日

本文适用于需要将接入了地图 JS API  v1.3 或者 v1.4.X 版本的地图应用升级到 v2.0 的开发者阅读。

JS API 2.0 提供的开发接口与 1.4 版本达到 99%的兼容度,我们建议开发者按照以下步骤对代码进行少许修改来升级 JS API 的版本,以便获得最佳的开发体验和后续服务支持。

升级步骤

1. 修改 JSAPI 引用中的版本号到 2.0。

<script src = 'https://webapi.amap.com/maps?v=2.0&key=您申请的key值' type="text/javascript" > </script>

这里只给出同步加载JSAPI 的使用方式,前往教程查看其他加载方式,比如异步加载、NPM 加载。

2. 如果你使用了以下功能,请按说明进行相应修改

1)默认图层创建方式变更

原来用法为 new AMap.TileLayer(),新的用法为 AMap.createDefaultLayer()

2)事件监听方式变更

AMap.event及其addEventListener()removeEventListener()等方法废弃

  • 给地图、覆盖物、图层绑定/移除事件时请使用实例的 on / off 方法
var map = new AMap.Map('conatainer');
var onMapClick = function( e ){
  //Do Somthing.
};
// 废弃方式
AMap.event.addEventListener(map,'event',onMapClick); // 添加事件
AMap.event.removeEventListener(map,'event',onMapClick); // 移除事件
// 推荐方式
map.on('click',  onMapClick); // 添加事件
map.off('click',  onMapClick); // 移除事件
  • 获取各种插件的回调结果的时候,使用回调方式替代事件监听方式
var geocoder = new AMap.Geocoder({
  city: "010", //城市设为北京,默认:“全国”
});
// 废弃用法
geocoder.getLocation(address);
AMap.event.addEventListener(geocoder, 'complete', function(result){
})
// 推荐用法
geocoder.getLocation(address, function(status, result) {
  // Do Something.
})

3)Marker 的moveTo()moveAlong()接口升级

这两个接口在JS API 2.0 版本本中需要先加载AMap.moveAnimation插件,插件加载完成之后,Marker 将都获得moveTo()moveAlong()的能力。

JS API 2.0 的 moveTo()moveAlong() 方法可以支持更丰富的设置,如动画持时间,动画延迟时间,及分段设置动画时间等。

// JSAPI2.0 moveTo 示例
AMap.plugin('AMap.MoveAnimation', function(){
  const animationMarker = new AMap.Marker({
    position: new AMap.LngLat(116.397389,39.909466),
  });
  animationMarker.moveTo([116.397389, 39.909466], {
    duration: 1000,
    delay: 500,
  });
});

// JSAPI2.0 moveAlong 示例
AMap.plugin('AMap.MoveAnimation', function(){
  const path = [
    new AMap.LngLat(116.397389, 39.909466),
    new AMap.LngLat(116.379707, 39.968168),
    new AMap.LngLat(116.434467, 39.95001),
    new AMap.LngLat(116.46365, 39.979481),
    new AMap.LngLat(116.397389, 39.909466),
  ];
  const customData = [
    { position: path[0], duration: 200 },
    { position: path[1], duration: 400 },
    { position: path[2], duration: 600 },
    { position: path[3], duration: 800 },
    { position: path[4], duration: 1000 },
  ];
  AMap.plugin('AMap.MoveAnimation', function(){
    const animationMarker = new AMap.Marker({
      position: new AMap.LngLat(116.397389,39.909466),
      angle: 90,
    });
    animationMarker.moveAlong(customData);
  });
});

4)Map 类个别方法名称变更

  • lnglatTocontainer() 变更为 lngLatToContainer()
  • project()变更为lngLatToPixel()
  • unproject()变更为pixelToLngLat()

5)覆盖物接口变更

  • 覆盖物setMap()方法废弃,同时不再支持配置项里的 map 配置,请使用map.add()方法进行添加。
  • Marker 的animation属性暂时不支持,可通过 CSS3 自行实现
  • Marker 的 label 的 offset 基准点由 Marker Dom 元素的左上角改为 label 的 direction 对应的方向的原点

6)插件名及类名变更

  • AMap.Autocomplete更名为AMap.AutoComplete
  • AMap.Heatmap更名为 AMap.HeatMap
  • AMap.MarkerClusterer更名为 AMap.MarkerCluster
  • AMap.PolyEditor拆分为AMap.PolygonEditorAMap.PolylineEditor
  • AMap.OverView更名为AMap.HawkEye,同时具有更强大的能力,比如:固定缩略图的显示区域,设置缩略图的图层类型、自定义地图样式等

7)GeoJSON 变更为插件

GeoJSON 变更为插件,使用前须通过插件引入,请参看示例

8)AMap.MarkerCluster  插件接口变更

使用时不需要先创建 Marker,而是直接将带有经纬度信息的聚合点数据传入构造函数中。请参看示例

9)  AMap.ToolBar 插件功能变更

ToolBar 插件只保留缩放功能,其他功能不再提供。请参看示例

10)  pitchrotationzoomcenter 设置方式新增动画参数控制

setPitch() / setRotation() / setZoom() / setCenter() / setZoomAndCenter() / panBy() / panTo() 方法新增参数 duration,可以控制动画过渡时长。例如:

mapObj.setPitch(
  50,  // 俯仰角 50 度
  false,  // 使用动画过渡
  1000,  // 动画时长 1000 毫秒
)

11)  AMap.Browser 变更AMap.Browser.isWebGL 从 function 变更为 boolean 值

12)  室内地图默认不显示,如果业务需要请设置 Map 初始属性showIndoorMap:true

13)2.0 版本暂不支持 海外地图、Object3D、自定义纹理 相关功能

3. 升级完成

如发现其他接口上的不兼容,可以通过工单方式进行反馈

使用适配器快速升级

JS API 2.0 提供了跨版本适配器— Adaptor 插件,对于一些希望快速升级 API 版本的应用可以使用 Adaptor 插件来避免大部分兼容问题,但是同时也将无法享受到新用法的全新特性,所以我们建议按照上面的升级步骤进行正常升级。

<script src='https://webapi.amap.com/maps?v=2.0&key=您申请的key值&plugin=AMap.Adaptor' type="text/javascript"></script>

返回顶部 示例中心 常见问题 智能客服 公众号
二维码