搜狗地图 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="//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="//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:
//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('//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="//map.sogou.com/#lq=%u4E94%u9053%u53E3&'+
  'c=12949886.71874925,4836859.375,16">'+
	'//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提供的服务有:

Geocoder:地址解析,提供将地址信息转换为坐标点信息的服务。

地理编码

用于在地址和 坐标之间进行转换的服务。

根据地址描述获得坐标

将一段地址描述转换为一个坐标。 下面的实例展示了我们对搜狐网络大厦进行定位后的标记。

/**
*地址解析
*/
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);