JSAPI 的加载 最后更新时间: 2022年03月15日
JS API 2.0 版本提供了两种方案引入地图 JSAPI:
1. 使用官网提供的 JSAPI Loader
进行加载;
2. 以常规 JavaScript
脚本的方式加载;
注意:为避免地图数据协议和前端资源不匹配导致页面运行报错,只允许在线加载 JSAPI,禁止进行本地转存、与其它代码混合打包等用法。
使用 JSAPI Loader (推荐)
JSAPI Loader
是我们提供的 API 加载器,可帮助开发者快速定位、有效避免加载引用地图 JSAPI 各种错误用法,具有以下特性:
- 支持以 普通JS 和 npm包 两种方式使用;
- 有效避免错误异步加载导致的 JSAPI 资源加载不完整问题;
- 对于加载混用多个版本 JSAPI 的错误用法给予报错处理;
- 对于不合法加载引用 JSAPI 给予报错处理;
- 支持指定 JSAPI 版本;
- 支持插件加载;
- 允许多次执行加载操作,网络资源不会重复请求,便于大型工程模块管理;
- 支持
IE9
以上的浏览器,不支持IE8
以下
按普通 JS 方式使用 Loader
使用Loader
<script src="https://webapi.amap.com/loader.js"></script>
<script type="text/javascript" >
AMapLoader.load({
"key": "", // 申请好的Web端开发者Key,首次调用 load 时必填
"version": "2.0", // 指定要加载的 JSAPI 的版本,缺省时默认为 1.4.15
"plugins": [], // 需要使用的的插件列表,如比例尺'AMap.Scale'等
"AMapUI": { // 是否加载 AMapUI,缺省不加载
"version": '1.1', // AMapUI 版本
"plugins":['overlay/SimpleMarker'], // 需要加载的 AMapUI ui插件
},
"Loca":{ // 是否加载 Loca, 缺省不加载
"version": '2.0' // Loca 版本
},
}).then((AMap)=>{
var map = new AMap.Map('container');
map.addControl(new AMap.Scale());
}).catch((e)=>{
console.error(e); //加载错误提示
});
</script>
注意(您在2021年12月02日申请以后的key需要配合您的安全密钥一起使用)
JSAPI key和安全密钥的使用
方式一【强烈建议】:
1)JSAPI key搭配代理服务器并携带安全密钥转发(安全)
1) 引入 JSAPI 使用 Loader
之前增加代理服务器设置脚本标签,设置代理服务器域名或地址,将下面示例代码中的「您的代理服务器域名或地址
」替换为您的代理服务器域名或ip地址
,其中_AMapService
为代理请求固定前缀,不可省略或修改。 (注意您这 个设置必须是在加载loader.js
的脚本引入之前进行设置,否则设置无效。)
<script type="text/javascript">
window._AMapSecurityConfig = {
serviceHost:'您的代理服务器域名或地址/_AMapService',
// 例如 :serviceHost:'http://1.1.1.1:80/_AMapService',
}
</script>
<script src="https://webapi.amap.com/loader.js"></script>
2)代理服务器的设置
以 Nginx 反向代理为例,参考以下三个location
配置,进行反向代理设置,分别对应自定义地图、海外地图、Web服务,其中自定义地图和海外地图如果没有使用到相关功能也可以不设置。需要将以下配置中的“您的安全密钥
”六个字替换为您刚刚获取的jscode安全密钥
。
server {
listen 80; #nginx端口设置,可按实际端口修改
server_name 127.0.0.1; #nginx server_name 对应进行配置,可按实际添加或修改
# 自定义地图服务代理
location /_AMapService/v4/map/styles {
set $args "$args&jscode=您的安全密钥";
proxy_pass https://webapi.amap.com/v4/map/styles;
}
# 海外地图服务代理
location /_AMapService/v3/vectormap {
set $args "$args&jscode=您的安全密钥";
proxy_pass https://fmap01.amap.com/v3/vectormap;
}
# Web服务API 代理
location /_AMapService/ {
set $args "$args&jscode=您的安全密钥";
proxy_pass https://restapi.amap.com/;
}
}
保存相关配置之后需要通过命令nginx -s reload
命令重新加载 nginx 配置文件
方式二【不建议】:
JSAPI key搭配静态安全密钥以明文设置(不安全,建议开发环境用):
引入 JSAPI 使用 Loader
之前增加代理服务器设置脚本标签,并将您的安全密钥「您申请的安全密钥
」替换为您的安全密钥;(注意:您这 个设置必须是在加载loader.js
的脚本之前进行设置,否则设置无效。)
<script type="text/javascript">
window._AMapSecurityConfig = {
securityJsCode:'「您申请的安全密钥」',
}
</script>
<script src="https://webapi.amap.com/loader.js"></script>
按 NPM 方式使用 Loader
安装:
npm i @amap/amap-jsapi-loader --save
使用:
import AMapLoader from '@amap/amap-jsapi-loader';
AMapLoader.load({
"key": "", // 申请好的Web端开发者Key,首次调用 load 时必填
"version": "2.0", // 指定要加载的 JSAPI 的版本,缺省时默认为 1.4.15
"plugins": [], // 需要使用的的插件列表,如比例尺'AMap.Scale'等
}).then((AMap)=>{
map = new AMap.Map('container');
}).catch(e => {
console.log(e);
})
注意(您在2021年12月02日申请以后的key需要配合您的安全密钥一起使用)
JSAPI key和安全密钥设置和使用的两种方式;方式一【强烈建议】:JS API key搭配代理服务器并携带安全密钥转发(安全)或,方式二【不建议】:JSAPI key搭配静态安全密钥以明文设置(不安全,建议开发环境用)。(具体两种使用方式请参考本文上一章节《JSAPI key和安全密钥的使用》介绍)。
直接加载 JSAPI 脚本
同步加载
注意:JSAPI异步加载的方式和同步加载方式两种方式,在使用获取的新key值必须搭配安全密钥一起使用(自2021年12月02日升级,升级之后申请的key必须配备安全密钥一起使用。)使用方式参考上一节中JSAPI key和安全密钥设置和使用。
同步加载指直接将 JSAPI 的的script
标签写入html
中,然后在之后的脚本中调用 JSAPI 的相关接口的使用方式
<div id='container' ></div>
<script src = 'https://webapi.amap.com/maps?v=2.0&key=您申请的key值'></script>
<script type="text/javascript" >
// 地图初始化应该在地图容器div已经添加到DOM树之后
var map = new AMap.Map('container', {
zoom:12
})
</script>
异步加载(特别注意)
异步加载指的是通过appendChild
将 JSAPI 的script
标签添加到页面中,或者给script
标签添加了async
属性的使用方式。这种使用场景下,JSAPI不会阻塞页面其他内容的执行和解析,但是 JSAPI 的脚本解析将有可能发生其他脚本资源执行之后,因为需要特别处理,以保证在AMap对象
完整生成之后再调用 JSAPI 的相关接口,否则有可能报错。
注意:异步回调函数的声明应该在 JSAPI 引入之前
// 声明异步加载回调函数
window.onLoad = function(){
var map = new AMap.Map('container');
}
var url = 'https://webapi.amap.com/maps?v=2.0&key=您申请的key值&callback=onLoad';
var jsapi = document.createElement('script');
jsapi.charset = 'utf-8';
jsapi.src = url;
document.head.appendChild(jsapi);
async
// 声明异步加载回调函数
<script type="text/javascript" >
window.onLoad = function(){
var map = new AMap.Map('container');
}
</script>
<script src="https://webapi.amap.com/maps?v=2.0&key=您申请的key值&callback=onLoad" async="async" type="text/javascript" ></script>