google maps api document 中文翻译- -
Tag： API,MAPS,GOOGLE
Google Maps API
可以让你在你自己的网页上嵌入google地图。要使用这个API,你需要上这里去
http://www.google.com/apis/maps/signup.htm
申请一个API key 并按照下面的说明来做。
这个API是新的，所以以完美的文档的要求来说，它可能会有一些小错误。容忍我们，我们将填补这些漏洞，您可以参加这个
Google Maps API 中文讨论区
http://groups.google.com/group/Goolgle-Map-Chinese
地图讨论组来反馈您的问题并讨论这个API。
正文如下：
介绍：
Google Maps的"helloword"程序
浏览器的选择
XHTML和VML
API更新
地理编码，路径选择等
例子：
最基本的
地图移动和动画
向地图中添加控件
事件监听
打开一个属性窗口
地图叠置
单击操作
在标记上的窗口显示信息
创建图标
使用图标类
在地图上使用XML和异步传输RPC（"AJAX"）
API 总览
GMap 类（the GMap class）
事件 （Event）
信息窗口（the info window）
叠置（Overlays）
图标和标记（Icons and Markers）
折线（Polylines）
控件（Controls）
XML 和 RPC
类参考
GMap
* Constructor
* Methods
* Configuration
* Controls
* State
* Overlays
* Info Window
* Event
GMarker
* Constructor
* Methods
* Events
GPloyLine
* Constructor
GIcon
* Constructor
* Properties
GEvent
* Static Methods
GXmlHttp
* Static Methods
GXml
* Static Methods
GXslt
* Static Methods
* Methods
GPoint
* Constructor
* Properties
GSize
* Constructor
* Propertes
GBounds
* Constructor
* Properties
简介：
Google Maps 的"hello world"实例
最简单的开始学习这个API的方法是看一个简单的例子。。这个网页显示了以Palo
Alto为中心的一个300×300的地图
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Google Maps JavaScript API Example - simple</title>
<script
src="http://maps.google.com/maps?file=api&v=1&key=abcdefg"type="text/javascript"></script>
</head>
<body>
<div id="map" style="width: 300px; height: 300px"></div>
<script type="text/javascript">
//<![CDATA[
if (GBrowserIsCompatible()) {
var map = new GMap(document.getElementById("map"));
map.centerAndZoom(new GPoint(-122.141944, 37.441944), 4);
}
//]]>
</script>
</body>
</html>
你可以把这个例子下载下来并编辑和测试它，但是你需要将"abcdefg"替换成你自己的Maps
API key，让这个例子能在你自己的网站上运行。
正如你在上面的例子中所看到的，Google
Maps引入了一个简单的javascript
url（http://maps.google.com/maps?file=api&v=1）,这个url包含了所有的在你的网页上创建地图的所需要的标记和符号。要使用Google
Maps
Api，你需要去创建一个简单的script标记来指向这个url，当然要加上你从google那里申请来的这个API的key。
<script
src="http://maps.google.com/maps?file=api&v=1&key=abcdefg"type="text/javascript"></script>
Google Maps
API输出的最主要的类是GMap类，它表现了一个网页上的简单的地图。你可以创建更多的这个类的实例（每个实例来表网页上的一个地图）。地图被嵌入到一个容器­-中，一般是一个div元素。
操纵和叠置图层到地图实例的方法会在下面详细介绍。
浏览器兼容性
Google Maps并不对所有的浏览器兼容。现在Google
Maps支持的浏览器版本有Firefox/Mozilla,IE5.5以上版本，Safari1.2以上版本部分支持Opera。它不支持IE5.0。由于不­-同的应用要求用户对不同的浏览器作不同的操作，Maps
API提供了一个globle
方法（GBrowserIsCompatible（））来检查兼容性，但是它没有任何自动的针对不同浏览器的行为。
脚本http://maps.google.com/maps?file=api&v=1将在几乎所有的浏览器上被正确解析，所以你可以在检查兼容性之前安全地将这个脚本引入进来。
除了上面的例子检测了兼容性外，本文档中的所有例子都没有检测兼容性，对于老的浏览器，他们也不会提示任何信息。显然，真正的应用中应该将事情做得更好，但是我­-们忽略了这些检查来让我们的例子更容易读。
XHTML 和 VML
我们推荐您再包含地图的网页上使用符合标准的XHTML。当浏览器检测到在页首的DOCTYPE标签时，它们将使用符合标准的模式来执行你的网页，这样可以使得­-在不同的浏览器上的布局和行为更加的可预料一些。
同样的，如果你在你的地图上要包含PLOYLINE，对于IE浏览器你需要在你的XHTML文档中引入VML名称空间。你的HTML文档应该这样开始：
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html
xmlns="http://www.w3.org/1999/xhtml"xmlns:v="urn:schemas-microsoft-com:vml">
<head>
<style type="text/css">
v\:* {
behavior:url(#default#VML);
}
</style>
<script
src="http://maps.google.com/maps?file=api&v=1&key=abcdefg"type="text/javascript"></script>
</head>
查看Microsoft VML workshop可以得到更多信息。
API 的更新
URl
http://maps.google.com/maps?file=api&v=1代表API的'1.0'版本。当我们要对这个API作出重大更新的时候，我们将增加版本号并在GOOGLE
CODE和MAP API讨论组发表通告。
我们将尝试同时运行新版本和旧版本，一个月后，老的版本就会被停用。
Maps团队将透明地更新API，包括增强它地性能，修复它的bugs。这些bugs修复工作只是为了提高性能和填补漏洞，但是我们可能会不经意地破坏一些AP­-I客户，请在Maps
API讨论组中报告这些情况。
地理编码，路径，等等
Google Maps
API还没有包含地理编码和路由服务，但网罗上有很多的免费的地理编码。
示例：
the basics
创建一副地图并将其中心定位在Palo Alto；
var map = new GMap(document.getElementById("map"));
map.centerAndZoom(new GPoint(-122.141944, 37.441944), 4);
map movement and animation
recenterOrPanToLatLng方法进行一个持续的漫游，如果经纬度范围不在当前的地图窗口中的话，另外它还可以进行一个离散的移动。
var map = new GMap(document.getElementById("map"));
map.centerAndZoom(new GPoint(-122.1419, 37.4419), 4);
window.setTimeout(function() {
map.recenterOrPanToLatLng(new GPoint(-122.1569, 37.4569));
}, 2000);
Adding Controls to the Map
你可以使用addControl方法往地图上添加控件。在这个例子中，我们添加了GSmallMapControl和GMapTypeControl，折使得我­-们能够缩放，漫游地图并在地图和卫星影像之间做切换。
var map = new GMap(document.getElementById("map"));
map.addControl(new GSmallMapControl());
map.addControl(new GMapTypeControl());
map.centerAndZoom(new GPoint(-122.141944, 37.441944), 4);
Event Listeners
事件监听器在GEvent.addListener方法中注册。在这个例子中，在用户将地图移动或者拖动以后，我们会返回地图的中间的经纬度坐标。
var map = new GMap(document.getElementById("map"));
GEvent.addListener(map, "moveend", function() {
var center = map.getCenterLatLng();
var latLngStr = '(' + center.y + ', ' + center.x + ')';
document.getElementById("message").innerHTML = latLngStr;
});
map.centerAndZoom(new GPoint(-122.141944, 37.441944), 4);
打开一个消息窗口(opening an info window)
显示一个指向地图中间的"hello
world"信息窗口。信息窗口一般的会在标签上方被打开,但是他们也可以在地图的任何地方被打开。
var map = new GMap(document.getElementById("map"));
map.centerAndZoom(new GPoint(-122.141944, 37.441944), 4);
map.openInfoWindow(map.getCenterLatLng(),
document.createTextNode("Hello world"));
地图叠加(Map Overlays)
创建了十个随机的标记和一个随机的折线来展示map
overlays的用途
// Center the map on Palo Alto
var map = new GMap(document.getElementById("map"));
map.addControl(new GSmallMapControl());
map.addControl(new GMapTypeControl());
map.centerAndZoom(new GPoint(-122.141944, 37.441944), 4);
// Add 10 random markers in the map viewport using the default icon
var bounds = map.getBoundsLatLng();
var width = bounds.maxX - bounds.minX;
var height = bounds.maxY - bounds.minY;
for (var i = 0; i < 10; i++) {
var point = new GPoint(bounds.minX + width * Math.random(),
bounds.minY + height * Math.random());
var marker = new GMarker(point);
map.addOverlay(marker);
}
// Add a polyline with 4 random points. Sort the points by longitude so
that
// the line does not intersect itself.
var points = [];
for (var i = 0; i < 5; i++) {
points.push(new GPoint(bounds.minX + width * Math.random(),
bounds.minY + height * Math.random()));
}
points.sort(function(p1, p2) { return p1.x - p2.x; });
map.addOverlay(new GPolyline(points));
单击操作(Click Handling).
当你点击地图的时候，你往那个点上面添加了一个标记。当你再次点击这个点的时候，你将这个点从地图上抹掉了。
var map = new GMap(document.getElementById("map"));
map.addControl(new GSmallMapControl());
map.addControl(new GMapTypeControl());
map.centerAndZoom(new GPoint(-122.141944, 37.441944), 4);
GEvent.addListener(map, 'click', function(overlay, point) {
if (overlay) {
map.removeOverlay(overlay);
} else if (point) {
map.addOverlay(new GMarker(point));
}
});
在标记上显示消息窗口(Display Info windows Above Markers)
在这个示例中，我们通过监听对每个标记的单击事件来显示一个定义的消息窗口，我们使用了关闭窗口的功能来对每个窗口的内容进行用户化的定制。
// Center the map on Palo Alto
var map = new GMap(document.getElementById("map"));
map.addControl(new GSmallMapControl());
map.addControl(new GMapTypeControl());
map.centerAndZoom(new GPoint(-122.141944, 37.441944), 4);
// Creates a marker whose info window displays the given number
function createMarker(point, number) {
var marker = new GMarker(point);
// Show this marker's index in the info window when it is clicked
var html = "Marker #<b>" + number + "</b>";
GEvent.addListener(marker, "click", function() {
marker.openInfoWindowHtml(html);
});
return marker;
}
// Add 10 random markers in the map viewport
var bounds = map.getBoundsLatLng();
var width = bounds.maxX - bounds.minX;
var height = bounds.maxY - bounds.minY;
for (var i = 0; i < 10; i++) {
var point = new GPoint(bounds.minX + width * Math.random(),
bounds.minY + height * Math.random());
var marker = createMarker(point, i + 1);
map.addOverlay(marker);
}
创建图标
创建一个新类型的图标，使用在Google Ride
Finder中的"mimi"标记作为例子。我们需要制定
这个图像的前景图像，阴影图像,以及我们想要将这些图标放在地图上的位置和和这些图标相对应的
信息窗口。
// Create our "tiny" marker icon
var icon = new GIcon();
icon.image = "http://labs.google.com/ridefinder/images/mm_20_red.png";
icon.shadow =
"http://labs.google.com/ridefinder/images/mm_20_shadow.png";
icon.iconSize = new GSize(12, 20);
icon.shadowSize = new GSize(22, 20);
icon.iconAnchor = new GPoint(6, 20);
icon.infoWindowAnchor = new GPoint(5, 1);
// Center the map on Palo Alto
var map = new GMap(document.getElementById("map"));
map.addControl(new GSmallMapControl());
map.addControl(new GMapTypeControl());
map.centerAndZoom(new GPoint(-122.141944, 37.441944), 4);
// Creates one of our tiny markers at the given point
function createMarker(point) {
var marker = new GMarker(point, icon);
map.addOverlay(marker);
GEvent.addListener(marker, "click", function() {
marker.openInfoWindowHtml("You clicked me!");
});
}
// Place the icons randomly in the map viewport
var bounds = map.getBoundsLatLng();
var width = bounds.maxX - bounds.minX;
var height = bounds.maxY - bounds.minY;
for (var i = 0; i < 10; i++) {
createMarker(new GPoint(bounds.minX + width * Math.random(),
bounds.minY + height * Math.random()));
}
使用图标类(Using Icon Classes)
在很多种情况下，你的图标也许会有相同的前景色，但可能有不同的形状和阴影。最简单的达到
这种效果的方法是使用GIcon
类的拷贝，这些拷贝将你所要定义的图标属性都拷贝到一个你所定义的
新的图标上去。
// Create a base icon for all of our markers that specifies the shadow,
icon
// dimensions, etc.
var baseIcon = new GIcon();
baseIcon.shadow = "http://www.google.com/mapfiles/shadow50.png";
baseIcon.iconSize = new GSize(20, 34);
baseIcon.shadowSize = new GSize(37, 34);
baseIcon.iconAnchor = new GPoint(9, 34);
baseIcon.infoWindowAnchor = new GPoint(9, 2);
baseIcon.infoShadowAnchor = new GPoint(18, 25);
// Center the map on Palo Alto
var map = new GMap(document.getElementById("map"));
map.addControl(new GSmallMapControl());
map.addControl(new GMapTypeControl());
map.centerAndZoom(new GPoint(-122.141944, 37.441944), 4);
// Creates a marker whose info window displays the letter corresponding
to
// the given index
function createMarker(point, index) {
// Create a lettered icon for this point using our icon class from
above
var letter = String.fromCharCode("A".charCodeAt(0) + index);
var icon = new GIcon(baseIcon);
icon.image = "http://www.google.com/mapfiles/marker" + letter +
".png";
var marker = new GMarker(point, icon);
// Show this marker's index in the info window when it is clicked
var html = "Marker <b>" + letter + "</b>";
GEvent.addListener(marker, "click", function() {
marker.openInfoWindowHtml(html);
});
return marker;
}
// Add 10 random markers in the map viewport
var bounds = map.getBoundsLatLng();
var width = bounds.maxX - bounds.minX;
var height = bounds.maxY - bounds.minY;
for (var i = 0; i < 10; i++) {
var point = new GPoint(bounds.minX + width * Math.random(),
bounds.minY + height * Math.random());
var marker = createMarker(point, i);
map.addOverlay(marker);
}
在地图上使用XML和异步远程方法调用Using XML and
Asynchronous RPC('AJAX')
在这个例子中，我们下载了一个静态文件"data.xml"，这个文件包含有一系列以XML存储的经纬度坐标。当下载完成后，我们解析这个XML文件并在每个经­-纬度交汇处，创建一个图标。
// Center the map on Palo Alto
var map = new GMap(document.getElementById("map"));
map.addControl(new GSmallMapControl());
map.addControl(new GMapTypeControl());
map.centerAndZoom(new GPoint(-122.141944, 37.441944), 4);
// Download the data in data.xml and load it on the map. The format we
// expect is:
// <markers>
// <marker lat="37.441" lng="-122.141"/>
// <marker lat="37.322" lng="-121.213"/>
// </markers>
var request = GXmlHttp.create();
request.open("GET", "data.xml", true);
request.onreadystatechange = function() {
if (request.readyState == 4) {
var xmlDoc = request.responseXML;
var markers =
xmlDoc.documentElement.getElementsByTagName("marker");
for (var i = 0; i < markers.length; i++) {
var point = new
GPoint(parseFloat(markers[i].getAttribute("lng")),
parseFloat(markers[i].getAttribute("lat")));
var marker = new GMarker(point);
map.addOverlay(marker);
}
}
}
request.send(null);
API 总览
GMap 类
GMap类的一个实例代表网页上的一个简单的地图。你可以为这个实例创建很多实例（这个网页上有多少地图，你就可以创建多少个）。一个地图被包含再一个容器中，­-一般来说是一个DIV元素。如果你没有明确地指出地图的尺寸，地图将会使用容器的大小来决定其大小。
GMap类提供一些方法来控制地图的空间位置（指定中心和缩放程度）和在地图上添加和移除叠加图层(overlays).它还提供了打开一个"消息窗口"的方法­-，这个"消息窗口"就是你再Google
Maps和Google
Local中所看到的。一个地图只有一个简单的消息窗口，所以在一个指定时间你只能看到一个窗口。
Event
你可以使用Event监听器往你的应用中动态地添加元素。一个对象提供了很多被命名的事件(Event),你的应用可以使用静态方法GEvent.addLis­-tener或者GEvent.bind监听这些事件。例如，下面的代码片断就在用户点击地图窗口时显示一个警告信息。
var map = new GMap(document.getElementById("map"));
GEvent.addListener(map, "click", function() {
alert("You clicked the map");
});
GEvent.addListener方法作为一个第三参数的函数存在，这个方法的使用需要引用一个事件处理函数在里面。如果你像要对一个方法类绑定一个事件，­-你可以使用GEvent.bind。例如：
function MyApplication() {
this.counter = 0;
this.map = new GMap(document.getElementById("map"));
GEvent.bind(this.map, "click", this, this.onMapClick);
}
MyApplication.prototype.onMapClick() {
this.counter++;
alert("You have clicked the map " + this.counter +
this.counter == 1 ?" time.":" times.");
}
var application = new MyApplication();
消息窗口(the info window).
Map
类有一个简单的"消息窗口"，可以在地图上方的浮动窗口内显示HTML内容。
最基本的"消息窗口"方法时openInfoWindow，这个方法使用一个点和一个HTML中的Dom元素作为参数。HTML
DOM元素被添加在消息窗口容器之后，消息窗口会显示在这个点上方。
openInfoWindowHtml也很相似，但是它以一个HTML字符串作为一个参数而不是一个DOM元素。
openInfoWindowsXslt以一个XML
DOM元素以及XSLT文档的URL来产生窗口内容，如果用户的浏览器没有下载下来的话，将异步地下载XSLT。
要在一个叠置图层（例如一个标记）上显示消息窗口，你可以通过一个可选的第三参数指定消息窗口
位置和你所指定的点之间的偏移量。例如，如果你的标记有10个象素高，你可以设置该象素便宜为GSize(0,-10).
GMarker类提供openInfoWindow方法来为你处理图标的大小和形状产生的象素偏移，所以你一般不需要为计算你应用中的图标偏移而担心。
叠置图层(Overlays)
叠置图层（似乎应该翻译为叠加物更为妥当）时在地图上的和经纬度坐标绑定的对象，所以它们会随
着你拖动/缩放或者变换地图投影的时候(例如变换地图模式到卫星模式的时候)。
Maps
API提供了两种类型的叠加物，一种是标记，他们是地图上的图标，另外一种是折线，他们是通
过经纬度坐标构成的。
图标和标记
GMarker类的构造器使用一个图标和一个点参数并提供一个小系列的事件对象(如单击)等等。上面的
ovrlay.htm例子就提供了一个简单的创建标记的例子。
创建标记最难的部分是指定图标，它比较复杂，是因为在Maps
API中，有相当多的不同的图像才构成
一个简单的图标。
每个图标有（至少有）一个前景图像和一个阴影图像。阴影图像需要从前景图像的45度角方位创建，
阴影图像的左下角必须与图标前景图像的左下角绑定在一起。阴影需要是一个24位的透明性为alpha
的PNG图像，这样其边缘才能在地图上方看起来正确。
GIcon类需要在你初始化它们的时候指定这些影像的尺寸，这样Maps
API才能创建合适大小的图像元
素。这是指定一个图标所需要的最小量的代码(在这里，图标是google
maps中使用)。
var icon = new GIcon();
icon.image = "http://www.google.com/mapfiles/marker.png";
icon.shadow = "http://www.google.com/mapfiles/shadow50.png";
icon.iconSize = new GSize(20, 34);
icon.shadowSize = new GSize(37, 34);
GIcon类提供了另外7个属性，你应该设定这些属性来使你的图标得到最多的浏览器兼容性和功能。例如，imageMap属性指定了图标图形中不透明的部分的形­-状。如果你没有在你的图标对象中设定这个属性，整个的图标图像（包括透明部分）将会在Firefox/Mozilla浏览器中变得可以点击的。查看GIcon­类-参考得到更多的消息。
折线(Polylines)
GPolyline类构造器使用一系列的经纬度二维数组作为参数。你可以指定线的颜色，宽度和透明度。颜色可以用老的HTML样式指定，如"#FF0000".­-GPloyline不懂得以颜色单词，如"red"命名的颜色。例如，下面的代码创建一个两点之间的10象素宽，红色的线。
var polyline = new GPolyline([new GPoint(-122.1419, 37.4419),
new GPoint(-122.1519, 37.4519)],
"#ff0000", 10);
map.addOverlay(polyline);
在IE浏览器中，我们使用VML来画多线。在其它的浏览器中，我们从google的服务器中请求线的图像
并将图像叠加在地图上，在地图被缩放和漫游时，酌情刷新地图。
控制器(Controls)
Controls使用addControl方法被添加上去.Maps
API提供了一套内嵌的控制器，你可以在地图里面使
用他们：
GLargeMapControl－一个在Google
Maps上的大的缩放/漫游工具。
GSmallMapControl－一个在Google
Local上的小一些的缩放/漫游工具
GSmallZoomControl-一个小的缩放工具，在Geegle
Maps上一个小的弹出窗口中使用它来显示一定的
方向。
GMapTypeControl－让你在不同的Map类型中进行切换（如map和satellite）
例如，要添加一个你在google
maps上看到的缩放/漫游控制器到你的地图上，你需要在你的地图初始
化时引入下面的一行代码
map.addControl(new GLargeMapControl());
XML和RPC
Google Maps
API提供了一个工厂方法来创建XmlHttpRequest对象，这些对象在近期版本的IE，
FireFox和Safari中都能使用。例如：
var request = GXmlHttp.create();
request.open('GET', "myfile.txt", true);
request.onreadystatechange = function() {
if (request.readyState == 4) {
alert(request.responseText);
}
}
request.send(null);
你可以使用静态方法Gxml.parse来解析一个XML文档，它只需要一个XML字符串作为唯一的参数。这个方法对所有的浏览器都兼容，如果浏览器没有本地的­-XML解析器的话，它将使用一个javascriptXML解析器作为后援。我们不能对这些后备的解析器在性能和正确性上作出任何保证。