准备 最后更新时间: 2023年01月30日
本章介绍使用高德地图 JS API 开发地图应用之前的一些准备工作。
注册账号并申请Key
1. 首先,注册开发者账号,成为高德开放平台开发者
2. 登录之后,再进入「应用管理」 页面「创建新应用」
3. 为应用添加 Key,「服务平台」一项请选择「 Web 端 ( JSAPI ) 」,设置域名白名单,可选(建议设置域名白名单)。
4. 添加成功后,可获取到key值和安全密钥jscode(自2021年12月02日升级,升级之后所申请的 key 必须配备安全密钥 jscode 一起使用)
注意:此次升级不会影响之前已获得 key 的使用;升级之后的新增的key必须要配备安全密钥一起使用,具体用法请您参看下文《JSAPI key和安全密钥设置和使用》(本次key升级新增安全密钥,是为了提升广大用户的对自己的key安全有效管理,降低明文传输被窃取的风险 。)
准备页面
1. 如果是移动端开发,请在head
标签内添加viewport
meta
标签,以达到最佳的绘制性能;
<meta name="viewport" content="initial-scale=1.0, user-scalable=no">
2. 添加div
标签作为地图容器,同时为该div
指定id
属性;
<div id="container"></div>
3. 通过 css
为地图容器指定高度、宽度;
#container {width:300px; height: 180px; }
4. JSAPI key和安全密钥的使用
方式一【强烈建议】:
1)JSAPI key搭配代理服务器并携带安全密钥转发(安全)
引入地图 JSAPI 脚本之前增加代理服务器设置脚本标签,设置代理服务器域名或地址,将下面示例代码中的「您的代理服务器域名或地址
」替换为您的代理服务器域名或ip地址
,其中_AMapService
为代理请求固定前缀,不可省略或修改。(注意您这个设置必须是在 JSAPI 的脚本加载之前进行设置,否则设置无效。)
<script type="text/javascript">
window._AMapSecurityConfig = {
serviceHost:'您的代理服务器域名或地址/_AMapService',
// 例如 :serviceHost:'http://1.1.1.1:80/_AMapService',
}
</script>
<script type="text/javascript" src="https://webapi.amap.com/maps?v=1.4.15&key=您申请的key值"></script>
2)代理服务器的设置
以 Nginx 反向代理为例,参考以下三个location
配置,进行反向代理设置,分别对应自定义地图、海外地图、Web服务,其中自定义地图和海外地图如果没有使用到相关功能也可以不设置。需要将以下配置中的“您的安全密钥
”六个字替换为您刚刚获取的jscode安全密钥
。如果您使用了多个key,需要在代理设置中根据 key来映射不同的安全密钥。
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 脚本之前增加设置 JSAPI 安全密钥的脚本标签,并将您的安全密钥「您申请的安全密钥
」替换为您的安全密钥;(注意这个设置必须是在 JSAPI 的脚本加载之前进行设置,否则设置无效。)
<script type="text/javascript">
window._AMapSecurityConfig = {
securityJsCode:'您申请的安全密钥',
}
</script>
<script type="text/javascript" src="https://webapi.amap.com/maps?v=1.4.15&key=您申请的key值"></script>
5. 除直接引入JSAPI 脚本之外,还可点击查看更多 JSAPI 加载方式(非常重要)
6. 在完成如上准备工作之后,您便可以开始参考后续文档进行开发了。
异步加载 JS API
上一节说明的是最基本的同步加载 JS API 的方式,如果您需要异步加载,比如通过appendChild
,或者通过require
等异步方式来加载,这时需要您需要先准备一个全局的回调函数作为 JS API 异步加载的回调函数,并将其函数名作为callback
参数添加在 JS API 的引用地址后面,此时要注意,回调函数应该在脚本请求发出之前进行声明。异步加载方式只有在回调之后,才能开始调用JSAPI的相关接口。比如
window.onLoad = function(){
var map = new AMap.Map('container');
}
var url = 'https://webapi.amap.com/maps?v=1.4.15&key=您申请的key值&callback=onLoad';
var jsapi = doc.createElement('script');
jsapi.charset = 'utf-8';
jsapi.src = url;
document.head.appendChild(jsapi);
注意:JS API异步加载的方式和同步加载方式两种方式,在使用获取的新key时必须搭配安全密钥一起使用(自2021年12月02日升级,升级之后申请的key必须配备安全密钥一起使用。)使用方式参考上一节中JSAPI key和安全密钥设置和使用。
更多的加载方式,请查看「JS API 的加载」
HTTPS 的支持
JSAPI 1.3 开始完全支持 HTTPS
协议,如需使用安全协议,替换 JS API 的入口脚本URL中的http
为https
即可。随着 Chrome、iOS 等相继限制非安全域的定位请求,我们建议您升级网站到HTTPS
协议,并使用HTTPS
协议加载 JS API。
注意:JS API加载的方式,在使用获取的新key值必须搭配安全密钥一起使用(自2021年12月02日升级,此次升级之后申请的key必须配备安全密钥一起使用。)使用方式参考上一节中JSAPI key和安全密钥设置和使用。
<script type="text/javascript" src="https://webapi.amap.com/maps?v=1.4.15&key=您申请的key值"></script>