搜狗地图 Javascript API2.0辅导手册

请认真阅读手册。将有助于您快速开发。

辅导手册-目录

应用开发

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="//api.go2map.com/maps/js/api_v2.0.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="//api.go2map.com/maps/js/api_v2.0.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); 

覆盖物

地图覆盖物概述

所有叠加或覆盖到地图的内容,我们统称为地图覆盖物。如标注、矢量图形元素(包括:折线和多边形和圆)、信息窗口等。覆盖物拥有自己的地理坐标,当您拖动或缩放地图时,它们会相应的移动。

地图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('//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('//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.sogo.com/#lq=%u4E94%u9053%u53E3&'+
  'c=12949886.71874925,4836859.375,16">'+
	'http://map.sogo.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);