控制台
您现在的位置： 开发 > 地图 JS API v2.0 > 教程 > 入门 > JSAPI 的加载

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 

HTML
<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的脚本引入之前进行设置，否则设置无效。）

HTML
<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安全密钥。

JavaScript
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的脚本之前进行设置，否则设置无效。）

HTML
<script type="text/javascript">
        window._AMapSecurityConfig = {
            securityJsCode:'「您申请的安全密钥」',
        }
</script>
<script src="https://webapi.amap.com/loader.js"></script>


相关示例 JSAPI  AMapUI Loca


按 NPM 方式使用 Loader

安装：

npm i @amap/amap-jsapi-loader --save

使用：

JavaScript
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  AMapUI Loca

直接加载 JSAPI 脚本

同步加载

注意：JSAPI异步加载的方式和同步加载方式两种方式，在使用获取的新key值必须搭配安全密钥一起使用（自2021年12月02日升级，升级之后申请的key必须配备安全密钥一起使用。）使用方式参考上一节中JSAPI key和安全密钥设置和使用。

同步加载指直接将 JSAPI 的的script标签写入html中，然后在之后的脚本中调用 JSAPI 的相关接口的使用方式

HTML
<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 引入之前

JavaScript
// 声明异步加载回调函数
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

HTML
// 声明异步加载回调函数
<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>
示例
中心 常见
问题 智能
客服