升级指南 最后更新时间: 2023年03月08日
本文适用于需要将接入了地图 JSAPI v1.3
或者 v1.4.X
版本的地图应用升级到 v2.0
的开发者阅读。
JSAPI 2.0 提供的开发接口与 1.4 版本达到 99%
的兼容度,我们建议开发者按照以下步骤对代码进行少许修改来升级 JSAPI 的版本,以便获得最佳的开发体验和后续服务支持。
升级步骤
1. 修改 JSAPI 引用中的版本号到 2.0
。
<script src = 'http://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
接口升级
这两个接口在API 2.0
版本中需要先加载AMap.moveAnimation
插件,插件加载完成之后,Marker
将都获得moveTo
和moveAlong
的能力。
JSAPI 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.PolygonEditor
和AMap.PolylineEditor
AMap.OverView
更名为AMap.HawkEye,
同时具有更强大的能力,比如:固定缩略图的显示区域,设置缩略图的图层类型、自定义地图样式等。
7)GeoJSON
变更为插件
GeoJSON 变更为插件,使用前须通过插件引入,示例中心
8)AMap.MarkerCluster
插件接口变更
使用时不需要先创建 Marker,而是直接将带有经纬度信息的聚合点数据传入构造函数中。请参看示例
9) AMap.ToolBar
插件功能变更
ToolBar 插件只保留缩放功能,其他功能不再提供。示例
10) pitch、rotation、zoom、center
设置方式新增动画参数控制
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. 升级完成
如发现其他接口上的不兼容,可以通过工单方式进行反馈
使用适配器快速升级
JSAPI 2.0 提供了跨版本适配器——Adaptor
插件,对于一些希望快速升级 API 版本的应用可以使用Adaptor
插件来避免大部分兼容问题,但是同时也将无法享受到新用法的全新特性,所以我们建议按照上面的升级步骤进行正常升级。
<script src='http://webapi.amap.com/maps?v=2.0&key=您申请的key值&plugin=AMap.Adaptor' type="text/javascript"></script>