开发 AMapUI 组件库 简介

简介 最后更新时间: 2022年08月15日

注意:本组件库已不再更新维护,如果有相关需求请使用 LOCA 和 JSAPI 其他功能代替。

UI组件库基于高德地图JavaScript API,侧重于帮助开发者快速实现地图上UI组件的个性化展示。 举例来说,Javascript API本身提供标准的Marker(即点标注)作为地图的基本功能,而UI组件库则提供更多颜色、样式的Marker(如下图),帮助开发者快速实现具备丰富效果的地图应用。JSAPI v2.0 版本需要使用AMapUI 组件库的 v1.1版本。

考虑到UI的多样性,UI组件库不仅提供了个性化地图组件的完整封装,且实现细节全部公开。开发者可以参考各个UI组件的实现代码,可以通过继承的方式进行局部修改,还可以通过替换某个模块(例如替换某个UI组件内部的dom结构)的方式来实现个性化的功能,具体细节请参见高级功能

环境准备

在高德地图JavaScript API之后引入UI组件库的入口文件:

<!--引入高德地图JSAPI -->
<script src="//webapi.amap.com/maps?v=2.0&key=您申请的key值"></script>

<!--引入UI组件库(1.1版本) -->
<script src="//webapi.amap.com/ui/1.1/main.js"></script>

如果使用了异步方式加载高德地图JSAPI,则需引入UI组件库的异步版本:

<!--异步加载 高德地图JSAPI ,注意 callback 参数-->
<script src="//webapi.amap.com/maps?v=2.0&key=您申请的key值&callback=my_init"></script>

<!--引入UI组件库异步版本main-async.js(1.1版本) -->
<script src="//webapi.amap.com/ui/1.1/main-async.js"></script>

<script type="text/javascript">
//JSAPI回调入口
function my_init() {
       initAMapUI(); //这里调用initAMapUI初始化
       //其他逻辑
}
</script>

组件加载

推荐使用AMapUI.loadUI接口加载特定UI,然后在回调函数中引用即可,比如:

AMapUI.loadUI([
    'overlay/SimpleMarker',//SimpleMarker
    'overlay/SimpleInfoWindow',//SimpleInfoWindow
    ],
function(SimpleMarker, SimpleInfoWindow) {
    //....引用加载的UI....
});

详细用法可参见各UI组件的使用说明以及示例中心

注意:应避免在循环体中进行 loadUI/load 调用。首先,load的目的是加载相关资源,无需执行多次;其次,load是异步操作,在同步执行的循环体中,代码执行顺序和代码书写顺序不一致,容易导致理解混乱。推荐的做法是:

//启动时一次加载所有依赖的组件
AMapUI.loadUI(['A', 'B'], function(A, B) {
    //初始化页面
    initPage(A, B);
});

function initPage(A, B) {
    //引用A,B,进行相关操作
    for(  .....  ){
         new A();
         new B();
         .......
    }
}



强制使用HTTPS

默认情况下,组件加载优先使用与应用页面相同的协议(https:下用https:,http:或者file:下用http:),如果需要强制https协议(比如file:场景下),可以在引入入口文件(main.js)之前定义如下全局变量 AMapUIProtocol

<script type="text/javascript">
var AMapUIProtocol = 'https:';  //注意结尾包括冒号
</script>
<!-- https 方式引入入口文件 -->
<script src="https://webapi.amap.com/ui/1.1/main.js"></script>

DomLibrary

部分UI依赖jQuery或者Zepto(参见具体UI的使用说明),需要设置DomLibrary的引用。如果使用的UI组件中并未涉及DomLibrary,可以跳过此项,不过,建议开发者统一设置,方便后续使用。

场景

细节

是否需要设置

当前页面在加载相关UI组件之前已经引入了jQuery或者Zepto

UI组件库直接引用存在的jQuery(window.jQuery)或者Zepto(window.Zepto)

无需设置

当前页面不涉及jQuery或者Zepto,而且引入它们也不会破坏现有的代码环境

UI组件库会在需要时动态加载相关的DomLibrary资源(PC环境下是jQuery,手机环境下是Zepto)

当前页面会动态加载jQuery或者Zepto,或者引入它们与现有的代码环境存在冲突(比如$命名冲突)

此种情况下需要您通过AMapUI.setDomLibrary明确设置,以避免相关冲突:

<script type="text/javascript">
    AMapUI.setDomLibrary($);//明确设置当前引用的$对象
</script>

需要设置

如果需要使用UI组件库引用的DomLibrary,可以用如下方法引入:

AMapUI.load(['lib/$'], function($){
   // $ 即为UI组件库最终使用的DomLibrary
});

版本升级

升级新版本需要您手动更新引用的UI组件库入口文件的地址,采用新的版本号(格式为x.y, 比如1.1):

<script src="//webapi.amap.com/ui/[版本号]/main.js"></script>

新版发布后,旧版本依然可用,不会删除。

我们会尽量维护版本之间的兼容性,但无法完全保证这一点,请您留意版本升级说明。

“UI”的感性因素较强,并非版本越“新”感觉越“好”,以您自身的效果需求为准即可,无需刻意追随新版本。

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