搜狗地图 Javascript API辅导手册
请认真阅读手册。将有助于您快速开发。
辅导手册-目录 |
应用开发
Hello, World!
开始学习搜狗地图API最简单的方式是看一个简单的示例。以下代码创建了一个地图并以搜狐网络大厦作为地图的中心：
<!DOCTYPE html>
<html>
<head>
<meta name="viewport" content="initial-scale=1.0, user-scalable=no" />
<meta http-equiv="content-type" content="text/html; charset=UTF-8"/>
<title>Sogou Maps JavaScript API v2 </title>
<style type="text/css">
html{height:100%}
body{height:100%;margin:0px;padding:0px}
#map_canvas{height:100%}
</style>
<script type="text/javascript" src="http://api.go2map.com/maps/js/api_v2.5.1.js"></script>
<script type="text/javascript">
function initialize() {
var myLatlng = new sogou.maps.LatLng(39.99226610365429,116.32591408950312);
var myOptions = {
'zoom': 17,
'center': myLatlng,
'mapTypeId': sogou.maps.MapTypeId.ROADMAP
}
var map = new sogou.maps.Map(document.getElementById("map_canvas"), myOptions);
}
</script>
</head>
<body onload="initialize()">
<div id="map_canvas"></div>
</body>
</html>
下面我们分步向您介绍：
准备页面
根据HTML标准，每一份HTML文档都应该声明正确的文档类型，我们建议您使用最新的符合HTML5规范的文档声明：
<!DOCTYPE html>
您也可以根据需要选择其他类型的文档声明，这样浏览器会以标准的方式对页面进行渲染，保证页面最大的兼容性。我们不建议您使用quirks模式进行开发。
下面我们添加一个meta标签，以便使您的页面更好的在移动平台上展示。
<meta name="viewport" content="initial-scale=1.0, user-scalable=no" />
接着我们设置样式，使地图充满整个浏览器窗口：
<style type="text/css">
html{height:100%}
body{height:100%;margin:0px;padding:0px}
#map_canvas{height:100%}
</style>
引用搜狗地图API文件
<script type="text/javascript" src="http://api.go2map.com/maps/js/api_v2.5.1.js"></script>
创建地图容器元素
地图需要一个HTML元素作为容器，这样才能展现到页面上。这里我们创建了一个div元素。
命名空间
搜狗地图的命名空间是 sogou.maps 所有的类都在此命名空间下。
创建LatLng对象
创建地图的中心点。可以是搜狗点坐标，也可以标准的经纬度。这里展示的是标准经纬度。
new sogou.maps.LatLng(39.99226610365429,116.32591408950312);
创建地图实例
设置地图的初始化参数。实例化地图。
var myOptions = {'zoom': 17,'center': myLatlng,'mapTypeId': sogou.maps.MapTypeId.ROADMAP}
var map = new sogou.maps.Map(document.getElementById("map_canvas"), myOptions);
适用于离线web应用
如果您正尝试开发基于HTML5离线存储特性的离线web应用（offline web app）,我们将逐步升级特性，以支持我们的地图api能最终完全离线使用。
将api加入到cache列表
就目前阶段，您可以将我们的api文件加入到您的manifest文件的CACHE列表内，使我们的api文件也能伴随您的其它需要缓存的文件一并缓存。
CACHE MANIFEST
CACHE:
http://api.go2map.com/maps/js/api_v2.5.1.js
覆盖物
地图覆盖物概述
所有叠加或覆盖到地图的内容，我们统称为地图覆盖物。如标注、矢量图形元素(包括：折线和多边形和圆)、信息窗口等。覆盖物拥有自己的地理坐标，当您拖动或缩放地图时，它们会相应的移动。
地图API提供了如下几种覆盖物：
Marker：标注表示地图上的点，可自定义标注的图标。
Label：表示地图上的文本标注，您可以自定义标注的文本内容。
Polyline：表示地图上的折线。
Polygon：表示地图上的多边形。多边形类似于闭合的折线，另外您也可以为其添加填充颜色。
Circle: 表示地图上的圆。
InfoWindow：信息窗口也是一种特殊的覆盖物，它可以展示更为丰富的文字和多媒体信息。
标注
标注表示地图上的点。API提供了默认图标样式，您也可以通过icon属性来指定自定义图标。Marker的构造函数的参数为 MarkerOptions。
var myLatlng = new sogou.maps.LatLng(39.981320,116.320247);
var MarkerOptions = {'zoom': 3,'center': myLatlng, 'mapTypeId': sogou.maps.MapTypeId.ROADMAP}
var map = new sogou.maps.Map(document.getElementById("map_canvas"), MarkerOptions);
var marker = new sogou.maps.Marker({'position': myLatlng,map: map});}
定义标注图标
下面的实例讲述了完整的Marker属性。
var myPoint = new sogou.maps.Point(12956867,4824730);
var myOptions = {
'zoom': 15,
'center': myPoint,
'mapTypeId': sogou.maps.MapTypeId.ROADMAP
}
var map = new sogou.maps.Map(document.getElementById("map_canvas"), myOptions);
/*************************************
* MarkerImage 类 示例 *
*************************************/
var image = new sogou.maps.MarkerImage('http://api.go2map.com/maps/images/v2.0/flag.png',
// 标记图标宽20像素，高32像素
new sogou.maps.Size(20, 32),
// 原点在图片左上角，设为(0,0)
new sogou.maps.Point(0,0),
// 锚点在小旗的旗杆脚上，相对图标左上角位置为(0,32)
new sogou.maps.Point(0, 32),
// 如果是合并的图片，必须设置此项，指定图片大小
// 如果是一张图片一个图标，此项可缺省。
new sogou.maps.Size(20, 32));
var shadow = new sogou.maps.MarkerImage('http://api.go2map.com/maps/images/v2.0/flag_shadow.png',
//阴影图标宽高
new sogou.maps.Size(37, 32),
new sogou.maps.Point(0,0),
new sogou.maps.Point(0, 32));
/*************************************
* MarkerShape 对象规范 示例 *
*************************************/
//shape定义点击的图标区域
//图片即使透明也是矩形的
//设置shape后，可以看到鼠标放在旗杆旁的右侧是不变小手的
var shape={
coord: [1,1,1,20,18,20,18 ,1],
type:'poly'
};
/*************************************
* MarkerOptions 对象规范 示例 *
*************************************/
var markerOptions={
//设置是否在鼠标悬停时显示Label
disableLabel:false,
//如果为 true，则可拖动标记。默认值为 false。
draggable:true,
//前景的默认图标 icon和icons使用其中一个即可
//如果同时存在，优先使用icons
//取值类型 String|MarkerImage|MarkerStyle
//可以是一个图片地址，也可以是MarkerImage或者MarkerStyle对象
icon:image,
//0 前景的默认图标，1 前景鼠标悬停时的图标
//icons:[],
//Marker的编号标识。
id:"ID00001",
//设置Label对象的参数。
//设置成初始即可见，相对于Marker居下对齐，
label:{visible:true,align:"BOTTOM"},
//显示标记的地图。
map: map,
//标记位置。必填。
position: myPoint,
//阴影图像。shadow和shadows使用其中一个即可
//如果同时存在，优先使用shadows
//取值类型 String|MarkerImage|MarkerStyle
//可以是一个图片地址，也可以是MarkerImage或者MarkerStyle对象
shadow:shadow,
//0 阴影默认图像，1 阴影鼠标悬停时图像。
//shadows:[],
//用于拖动/点击的图像地图区域定义。
shape:shape,
//Label文本或者鼠标悬停时显示的tip。
title:"小旗可以拖动哦",
//如果为 true，则显示标记。默认为true
visible:true,
//叠加顺序
zIndex:0
};
var marker = new sogou.maps.Marker(markerOptions);
监听标注事件
事件方法与Map事件机制相同。可参考Marker事件部分。
var marker=new Marker({map:Map实例,position:位置});
sogou.maps.event.addListener(marker,"click", function(){ alert("您点击了标注"); });
可托拽的标注
默认情况下标注不支持拖拽，您需要调用marker.setDraggable(true)方法来开启拖拽功能。在标注开启拖拽功能后，您可以监听标注的dragend事件来捕获拖拽后标注的最新位置。
marker.setDraggable(true);
sogou.maps.event.addListener(marker,"dragend", function(){
alert("当前位置：" + marker.getPosition());
})
信息窗口
信息窗口在地图上方的浮动显示HTML内容。信息窗口可直接在地图上的任意位置打开，也可以在标注对象上打开（此时信息窗口的坐标与标注的坐标一致）。 您可以使用InfoWindow来创建一个信息窗实例。下面的实例展示了点击标注显示信息窗的方法。
var myLatlng = new sogou.maps.LatLng(39.992792,116.326142);
var myOptions = {
'zoom': 15,
'center': myLatlng,
'mapTypeId': sogou.maps.MapTypeId.ROADMAP
}
var map = new sogou.maps.Map(document.getElementById("map_canvas"), myOptions);
var contentString = '<div id="content">'+
'<div id="siteNotice">'+
'</div>'+
'<h1 id="firstHeading" class="firstHeading">五道口</h1>'+
'地图：'+
'<a target="_blank" href="http://map.sogou.com/#lq=%u4E94%u9053%u53E3&'+
'c=12949886.71874925,4836859.375,16">'+
'http://map.sogou.com/#lq=%u4E94%u9053%u53E3&c=12949886.71874925,4836859.375,16</a> '+
'<div id="bodyContent">'+
'<p><b>五道口</b>, 由于是从北京北站出发的京包铁路的第五个道口，故名“五道口”，'+
'而其前后各有“四道口”、“六道口”。目前并没有修建立体道口，'+
'所以列车通过时需要围栏挡住过往车辆行人通行，随着该地区交通量不断增大，'+
'经常造成交通堵塞。'+
'</p>'+
'<p>早年间，西直门外以北地区人烟稀少，以后才有人在此开垦出庄稼地，'+
'因多有车马往来，便人为地走出几条大道。上个世纪初期，自西直门火车站'+
'（今北京北站）由南向北修建了一条铁路（今京包铁路），于是就出现了一些与铁路交叉的道口，'+
'并自南向北称为第一道口、第二道口、第三道口、第四道口、第五道口等，以后简称为一道口、'+
'二道口、三道口、四道口、五道口。随着铁路沿线地区居住人员的增多，在一些道口附近逐渐形成村落，'+
'并依道口之名得村名，称四道口村、五道口村、六道口村等，而没有形成村落的道口就被人们逐渐地遗忘了。'+
'但也有人认为五道口因是五个路口的交会处而得名，是从五个方向在此交会的路口，此说难以考证。 , '+
'</p>'+
'</div>'+
'</div>';
var infowindow = new sogou.maps.InfoWindow({
content: contentString
});
var marker = new sogou.maps.Marker({
position: myLatlng,
map: map,
//设置信息窗上方标题栏的文字
title: '五道口简介'
});
sogou.maps.event.addListener(marker, 'click', function() {
infowindow.open(map,marker);
});
折线
Polyline表示地图上的折线覆盖物。它包含一组点，并将这些点连接起来形成折线。
添加折线
折线在地图上绘制为一系列直线段。可以自定义这些线段的颜色、粗细和透明度。颜色可以是十六进制数字形式（比如：#ff0000）。
Polyline的绘制需要浏览器支持矢量绘制功能。在Internet Explorer中，地图使用VML绘制折线；在其他浏览器中使用SVG或者Canvas
以下代码段会创建6像素宽的蓝色折线：
var myLatLng = new sogou.maps.LatLng(39.988176,116.319404);
var myOptions = {'zoom': 15,'center': myLatLng,'mapTypeId': sogou.maps.MapTypeId.TERRAIN};
var map = new sogou.maps.Map(document.getElementById("map_canvas"), myOptions);
//坐标可以是经纬度坐标，也可以是搜狗坐标
var flightPlanCoordinates = [
new sogou.maps.LatLng(39.992792,116.326142),
new sogou.maps.Point(12949589,4835996),
new sogou.maps.LatLng(39.986017,116.31049)
];
var flightPath = new sogou.maps.Polyline({
path: flightPlanCoordinates,
strokeColor: "#0000FF",
strokeOpacity: 1.0,
strokeWeight: 6
});
flightPath.setMap(map);
事件
地图事件概述
浏览器中的JavaScript是“事件驱动的”，这表示JavaScript通过生成事件来响应交互，并期望程序能够“监听”感兴趣的活动。
例如，在浏览器中，用户的鼠标和键盘交互可以创建在DOM内传播的事件。对某些事件感兴趣的程序会为这些事件注册JavaScript事件监听器，并在接收 这些事件时执行代码。
搜狗地图API拥有一个自己的事件模型，程序员可监听地图API对象的自定义事件，使用方法和DOM事件类似。但请注意，地图API事件是独立的，与标准DOM事件不同。
事件监听
可使用sogou.maps.event.addListener() 事件处理程序注册以接收事件通知。在特定环境下这些事件会被触发，同时监听函数会得到相应的事件参数e，比如当用户点击地图时，参数会包含鼠标所对应的地理位置。
有关地图API对象的事件，请参考完整的API参考文档。
该方法有三个参数，一个对象，一个待侦听事件以及一个在指定事件发生时调用的函数。
var myLatlng = new sogou.maps.LatLng(39.992792,116.326142);
var myOptions = {'zoom': 12,'center': myLatlng,'mapTypeId': sogou.maps.MapTypeId.ROADMAP}
map = new sogou.maps.Map(document.getElementById("map_canvas"), myOptions);
//添加侦听器，当点击标记时触发，将地图缩放到第8级
sogou.maps.event.addListener(marker, 'click', function() {
map.setZoom(8);
});
事件参数
在标准的DOM事件模型中（DOM Level 2 Events），监听函数会得到一个事件对象e，在e中可以获取有关该事件的信息。
搜狗地图API的事件模型与此类似，在事件监听函数中传递事件对象e，每个e参数包含传递的信息。
例如，通过参数e得到点击的经纬度坐标。
sogou.maps.event.addListener(map, 'click', function(e) {
//获取点击位置的坐标
alert(e.point)
});
移除监听事件
当您不再希望监听事件时，可以将事件监听进行移除。每个API对象提供了removeListener用来移除event.addListener 传回的指定侦听器。
请参考API类库中的具体内容。
服务
地图服务概述
地图服务是指那些提供数据信息的接口，比如本地搜索、路线规划等等。搜狗地图API提供的服务有：
Search：搜索，搜索功能很强大。提供某一特定地区的位置搜索服务，信息分类搜索，以及组合搜索。
Bus：公交导航，提供某一特定地区的公交出行方案的搜索服务。
Driving：驾车导航，提供驾车出行方案的搜索服务。
Geocoder：地址解析，提供将地址信息转换为坐标点信息的服务。
搜索
搜索使用起来很简单，在进行搜索时只需要配置SearchRequest对象即可。下面是一个简单的实例。在当前视野内搜索搜狐网络大厦。
var myLatLng = new sogou.maps.Point(12957062,4827187);
var myOptions = {'zoom': 10,'center': myLatLng};
var map = new sogou.maps.Map(document.getElementById("map"), myOptions);//创建地图
var request={
'map':map,
'what':{
'keyword':'搜狐网络大厦'
},
'range':{
'boundFlag':2 //当前视野搜索
}
};
var search=new sogou.maps.Search();//创建搜索实例
search.search(request);//进行搜索
search.setRenderer(new sogou.maps.SearchRenderer());//在地图上显示结果标记
配置搜索
SearchRequest提供了若干属性，通过它们可以自定义搜索服务的行为以满足您的需求。具体参考服务类库。
结果面板
通过sogou.maps.SearchRenderer()可以为本地搜索对象提供一个结果列表容器,以及指定地图，搜索结果会自动添加到容器元素和地图中。 请看下面示例：
var myLatLng = new sogou.maps.Point(12957062,4827187);
var myOptions = {
'zoom': 10,
'center': myLatLng
};
var map = new sogou.maps.Map(document.getElementById("map"), myOptions);//创建地图
//指定Div容器
var sRender=new sogou.maps.SearchRenderer({'panel':document.getElementById('result')});
var request={
'map':map,
'what':{
'keyword':'搜狐网络大厦'
}
};
var search=new sogou.maps.Search();//创建搜索实例
search.search(request);
search.setRenderer(sRender);
周边搜索
周边搜索可以进行以某一点为中心的周边的查询。下面的实例搜索的是西单北大街附近的银行。当然范围可根据你的需要进行设置。详情请您参考服务类库。
var myLatLng = new sogou.maps.Point(12957062,4827187);
var myOptions = {
'zoom': 10,
'center': myLatLng
};
var map = new sogou.maps.Map(document.getElementById("map"), myOptions);//创建地图
var sRender=new sogou.maps.SearchRenderer();//搜索渲染对象。
var request={
'map':map,
'what':{
'keyword':'银行'
},
'range':{
''center'':new sogou.maps.Point(12954160.15625039,4825117.1875),
'radius':1000,
'limit':1 //严格限制半径
}
};
var search=new sogou.maps.Search();//创建搜索实例
search.search(request);
search.setRenderer(sRender);
公交导航
公交导航的区域范围只能是市，而不能是省。如果你指定了公交渲染对象，结果将自动添加到地图上。sogou.maps.Bus()的route()方法只是查询出所有的换乘方案。若想查看其中一条方案详情可以通过sogou.maps.BusDetail()获得。下面是简单的展示了公交导航的使用方法。详情 请参考服务类库。
var myLatLng = new sogou.maps.Point(12957062,4827187);
var myOptions = {
'zoom': 10,
'center': myLatLng
};
var map = new sogou.maps.Map(document.getElementById("map"), myOptions);
var bRender=new sogou.maps.BusRenderer();//公交渲染对象
var request={
'map':map, //Map
'destination':'搜狐网络大厦',//目标位置。要进行地址解析的字符串或 LatLng或者为搜狗地图坐标。必填。
'origin':'西单' //原点的位置。要进行地址解析的字符串或 LatLng或者为搜狗地图坐标。必填。
}
var bus=new sogou.maps.Bus();
bus.route(request);
bus.setRenderer(bRender);
结果面板
如果指定了sogou.maps.BusRenderer()对象。公交的结果会绘制到地图上以及指定的结果<div>区。如果只想将一条换乘方案的详情绘制到指定的面板中，请参考sogou.maps.BusDetailRenderer以及我们提供的更多实例。下面的实例只是简单的展示如何定义一下结果面板。
var myLatLng = new sogou.maps.Point(12957062,4827187);
var myOptions = {
'zoom': 10,
'center': myLatLng
};
var map = new sogou.maps.Map(document.getElementById("map"), myOptions);
function callback(a){
var option={
'map':map,
'panel':document.getElementById('result'), //div 结果显示区
'busResult':a
};
var bRender=new sogou.maps.BusRenderer(option);
};
var request={
'map':map, //Map
'destination':'搜狐网络大厦',//目标位置。要进行地址解析的字符串或 LatLng或者为搜狗地图坐标。必填。
'origin':'西单', //原点的位置。要进行地址解析的字符串或 LatLng或者为搜狗地图坐标。必填。
'maxDist':1000//最大的步行距离。可选
}
var bus=new sogou.maps.Bus();
bus.route(request,callback);
驾车导航
与公交导航不同的是，驾车导航的搜索范围可以设置为省。
下面示例展示了如何使用驾车导航接口：
var myLatLng = new sogou.maps.Point(12957062,4827187);
var myOptions = {
'zoom': 10,
'center': myLatLng
};
var map = new sogou.maps.Map(document.getElementById("map"), myOptions);
var request={
'map':map,
'destination':'搜狐网络大厦',
'origin':'西单北大街',
'tactic':0
}
var nav=new sogou.maps.Driving();
nav.route(request);
nav.setRenderer(new sogou.maps.DrivingRenderer());
结果面板
下面示例中，我们提供了结果渲染对象sogou.maps.DrivingRenderer，指定了结果面板，方案描述会自动展示到页面上。
var myLatLng = new sogou.maps.Point(12957062,4827187);
var myOptions = {
'zoom': 10,
'center': myLatLng
};
var map = new sogou.maps.Map(document.getElementById("map"), myOptions);
var request={
'map':map,
'destination':'搜狐网络大厦',
'origin':'西单北大街',
'tactic':2 //驾车策略。 0： 距离短；1 ：时间短 默认策略 （不选为1）；2 ：不走高速
}
var nav=new sogou.maps.Driving();
nav.route(request);
//面板
nav.setRenderer(new sogou.maps.DrivingRenderer({'panel':document.getElementById('result')}));
地理编码
用于在地址和 坐标之间进行转换的服务。
根据地址描述获得坐标
将一段地址描述转换为一个坐标。 下面的实例展示了我们对搜狐网络大厦进行定位后的标记。
/**
*地址解析
*/
var myLatLng = new sogou.maps.Point(12949482.781246997,4837105.69140625);
var myOptions = {
'zoom': 15,
'center': myLatLng
};
var map = new sogou.maps.Map(document.getElementById("map"), myOptions);
function callback(a){//回调函数 标点
if(a.status='ok'){
var geometry=a.data[0];
new sogou.maps.Marker({
map:map,
title:geometry.address,
position:geometry.location
});
}
};
var request={address:{addr:'搜狐网络大厦',city:'北京'}}
var geo=new sogou.maps.Geocoder();
geo.geocode(request,callback);
反向地理编码
反向地理编码的过程正好相反，它根据一个坐标点得到一个地址的描述。您可以通过配置GeocoderRequest().location属性指定坐标。当解析工作完成后，您提供的回调函数将会被触发。如果解析完成，则回调函数的参数为GeocoderResult对象。
/**
*反地址解析
*/
var myLatLng = new sogou.maps.Point(12949482.781246997,4837105.69140625);
var myOptions = {
'zoom': 17,
'center': myLatLng
};
var map = new sogou.maps.Map(document.getElementById("map"), myOptions);
function callback(a){
if(a.status='ok'){
var geometry=a.data[0];
new sogou.maps.Marker({
map:map,
title:geometry.address,
position:geometry.location
});
}
};
var request={
location:{
points:[
new sogou.maps.Point(12949482.781246997,4837105.69140625),
new sogou.maps.Point(12948892.218746996,4835609.52734375)
],
type:0
}
}
var geo=new sogou.maps.Geocoder();
geo.geocode(request,callback);