第一章：谷歌地图 Javascript API V3 基础

注意：现在这些页面文档就是 Google Maps Javascript API 第三版本的官方版本。按照我们既定的原则强烈建议不要再使用第二个版本的API。我们强烈建议您修改代码以便迁移到经过修改和增强的新版本。

欢迎来到最新修改并发布的官方第三个版本谷歌地图 API。第三个版本的API已经正式地替代了第二个版本的API。版本看起来好像差不多，但实际上已经有了很大的改变：

第三个版本在设计上使得加载更加快速，尤其是在例如基于Android和IPhone系统的移动设备浏览器上。

我们欢迎您就这个版本的 Google Maps API 在 Google Maps API V3 讨论组发表自己的看法和建议。

欢迎来到第三个版本

读者

地理定位

测定用户的地理位置

传感设备参数具体说明

移动设备上的开发(包含基于IPhone 和 Android 系统的设备)

第三个地图版本的本地化

异步加载API

版本

版本类型

版本说明

问题处理

欢迎来到第三个版本
欢迎来到发布的谷歌地图第三个版本的API。这个版本的JavaScript API 看起来和已经存在的第二个版本的API 没说明差别。不过，其实里面很多东西已经发生了改变：第三个版本（在本文档之中称之为V3）的设计得使加载更加快速，特别是例如在基于 Android 和Iphone 系统移动设备的浏览器上。比起第二个版本提供的初始化参数略有减少。我们在迁移代码时通过增加特性来使得可以确保大量的 JavaScript 代码只需要经过很小的修改就可以获得最佳的加载速度。我们欢迎您就第三个版本的API 在 Google Maps API V3 讨论组中发表自己的看法和建议。

我们实现了在最新版本的谷歌地图API 中使用经过修改的 MVC 架构。一个MVC的对象，如地图（任何状态的改变为例子），通过setter和getter方法的以一个特定的格式进行处理。而且，所有的MVC对象的状态存储为这一对象的属性，并通过事件观察和特定的格式处理程序地图所有状态的变化。

特别需要强调的是在一些对于可靠性和性能要求较高的移动设备浏览器上已经集成了API。我们鼓励您通过测试移动设备及特定设备上的API来验证上面提到的观点。

注意：使用这个版本的谷歌地图API已经不再需要 API Keys ！

读者
本设计文档面向熟悉JavaScript 编程和面向对象编程思想的读者。您还应该熟悉谷歌地图使用者的观点。在网上有很多JavaScript 教程。

本设计文档的宗旨是使您能够使用谷歌地图API快速启动和开发出很好的应用程序。我们还发布了谷歌地图API手册。

在概念上本文档分为以下几个部分：

基本地图对象

地图事件

地图控件

地图覆盖物(涂层)

地图服务

欢迎就这个版本的API和本文档进行反馈。核对后反馈给第三个版本谷歌地图JavaScript API 组。

地理定位
地理定位是指计算设备通过鉴定一个用户的地理位置数据集合和各种机制来确定其真实地理位置。通常情况下，大多数地理定位通过使用网络服务的路由地址或设备内置的GPS来进行地理定位。请注意，地理定位是一个浏览器/设备特定的API，有些浏览器/设备的支持，有的则没有（或不支持），所以你不能认为一个Web地理定位应用程序总是可以进行地理定位。

测定用户的地理位置
目前，有几个不同的测定用户地理位置的方法存在于浏览器。这些方法都没有使用谷歌地图API；反而，它们都是公共的行业标准。

新浏览器都开始支持 W3C 地理定位标准。这个标准是HTML5的一部分，并为成为事实上的标准而改进。所有应用软件希望运行地理定位都需要支持这一标准。

一些带有谷歌W3C标准变体的浏览器可以使用谷歌的地理定位API。由于支持W3C标准依然是趋势，这是一个很好的回归标准的机会。

一些浏览器通过用户的IP地址来进行测定用户的地理位置，只是通过IP地址来进行测定是非常不准确的。

通过一个用户的IP地址，只能提供其位置的粗略估计，我们不建议使用此方法测定地理位置。W3C的方法是最简单，最完全的支持，所以它应该比其他的方法优先使用。如果你决定使用谷歌W3C变体，你应该先检查浏览器是否支持W3C标准。(注意使用谷歌W3C变体需要下载变体初始化Javascript )。

下面的示例首先尝试通过W3C的navigator.geolocation属性来确定用户的位置，然后尝试使用谷歌变体的方法，如果都不能正常使用则测定失败。

// Note that using Google Gears requires loading the Javascript

//注意使用谷歌变体需要加载的 Javascript
// at http://code.google.com/apis/gears/gears_init.js

//地址在 http://code.google.com/apis/gears/gears_init.js

var initialLocation;
var siberia = new google.maps.LatLng(60, 105);
var newyork = new google.maps.LatLng(40.69847032728747, -73.9514422416687);
var browserSupportFlag = new Boolean();

function initialize() {
var myOptions = {
    zoom: 6,
    mapTypeId: google.maps.MapTypeId.ROADMAP
};
var map = new google.maps.Map(document.getElementById("map_canvas"), myOptions);

// Try W3C Geolocation (Preferred)
if(navigator.geolocation) {
    browserSupportFlag = true;
    navigator.geolocation.getCurrentPosition(function(position) {
      initialLocation = new google.maps.LatLng(position.coords.latitude,position.coords.longitude);
      map.setCenter(initialLocation);
    }, function() {
      handleNoGeolocation(browserSupportFlag);
    });
// Try Google Gears Geolocation
} else if (google.gears) {
    browserSupportFlag = true;
    var geo = google.gears.factory.create(\'beta.geolocation\');
    geo.getCurrentPosition(function(position) {
      initialLocation = new google.maps.LatLng(position.latitude,position.longitude);
      map.setCenter(initialLocation);
    }, function() {
      handleNoGeoLocation(browserSupportFlag);
    });
// Browser doesn\'t support Geolocation
} else {
    browserSupportFlag = false;
    handleNoGeolocation(browserSupportFlag);
}

function handleNoGeolocation(errorFlag) {
    if (errorFlag == true) {
      alert("Geolocation service failed.");
      initialLocation = newyork;
    } else {
      alert("Your browser doesn\'t support geolocation. We\'ve placed you in Siberia.");
      initialLocation = siberia;
    }
    map.setCenter(initialLocation);
}
}

View example (map-geolocation.html) 查看示例

传感设备参数具体说明
谷歌地图API使用时要求您说明您的应用程序是否正在使用如（全球定位系统定位的传感器GPS）来确定用户的位置。这是一个特别重要的移动设备。应用程序必须通过向<script>标记内的地图Javascript API 的JavaScript代码中添加传感器参数，来表明您的应用程序是否正在使用一个传感器设备。

如果应用程序通过一个传感器来确定用户的位置就必须在加载地图JavaScript API时设置 sensor=true。

#
# Example using sensor when loading the Maps JavaScript API

# 一个使用传感器时加载地图 JavaScript API的例子
#
<script type="text/javascript" src="http://maps.google.com/maps/api/js?sensor=true"></script>

请注意，即使您的设备没有使用传感器设备，还是必须设置这个参数，设置为false。

移动设备上的开发(包含基于IPhone 和 Android 系统的设备)
第三个版本的谷歌地图API的设计使得在移动设备上加载更加快速。特别是，我们把重点放在先进移动设备上的开发，如运行iPhone和Android操作系统的手机。移动设备上使用比桌面上更小的典型浏览器。而且，他们往往拥有针对这些设备的（iPhone的触屏放大）行为。如果你希望你的应用程序在移动设备更好地工作，我们提出以下建议：

设置包含您地图的<div>宽度和高度属性为100%。这样是很好的显示方式，但是一些旧的桌面浏览器不会以这样的方式来显示。

在iPhone和Android设备上，您可以检查DOM内的navigator.userAgent属性。

这使得您可以更改特定的设备布局，在这里为我们所做的改变不管每个设备实际的屏幕大小。Nín kěyǐ tōngguò jiǎnchá fāxiàn de DOM nèi navigator.UserAgent shǔxìng iPhone hé Android shèbèi:

在iPhone设备中请尊重<meta>标记：

此设置指定显示地图时为全屏幕，用户不能进行调整。Android设备上运行的软件版本在1.5以上时也支持这些参数。请注意，iPhone的Safari浏览器需要此<meta>标记被包含在页面的<head>元素内。

想了解更多关于iPhone开发的信息，咨询苹果开发者文档（Apple\'s Developer documentation）。想了解更多关于Android设备开发的信息，咨询Android 开发文档（Android documentation）。

第三个地图API版本的本地化
你可以通过设置应用程序的区域代码改变本地化默认的语言设置和改变您的地图API应用程序对某一国家或地区的行为。

语言本地化
谷歌地图API使用浏览器的首选语言设置为控件显示的首选语言，如姓名，版权声明行车路线和地图上的标签，文字资料显示的语言。在大多数情况下，这是可取的，您通常不希望覆盖用户的首选语言设置。不过，如果你想使地图API忽略浏览器的语言设置，迫使它显示在一个特定的语言信息，您可以在包括地图API的JavaScript代码的<script>标记内添加一个可选的语言参数，并注明语言的使用。

例如，要API应用程序显示日本地图时，在<script>标记内添加＆language= ja，如下所示：

注意：这样装载，所有用户界面将使用日语，请确保所有用户喜欢这样的方式，再进行这个设置选项的行为。

查看示例(map-language.html)

该地图JavaScript API还支持双向（比迪）文本字符语言识别（包含从左到右（LTR）的和从右到左（RTL））能力。RTL语言的例子包括阿拉伯语，希伯来语和波斯语。一般来说，你应该在指定RT语言的网页<html>元素内加入dir=\'rt1\'来使页面渲染（显示）正常。下面的例子呈现了开罗地图，埃及使用用阿拉伯语。

查看示例（map-rtl.html）

请参考支持的语言列表(supported list of languages). 请注意，我们经常更新支持的语言使得这个名单可能不是最详细的。

区域化
地图的地图API服务默认的显示和应用程序行为，为使用API加载的主服务器所在的国家（maps.google.com 在美国）。如果你想改变你的显示和应用程序行为，如设置对应区域地理编码不同的地区显示不同的地图和应用程序行为，您可以通过添加一个覆盖区域参数在加载地图API代码的<script>标记内。

该地区的Unicode参数接受该地区的子标记标识符（一般）有一对一的映射到国家代码*域名（ccTLDs）的。大多数地区的Unicode标识符是相同的ISO 3166-1代码，有一些则不太相同。例如，英国的国家代码*域名是“英国”（对应的域名是co.uk），而该地区的标识符是“GB”。

例如，要使用API应用程序本地化的英国地图，添加&region= GB在<script>标记内，如下所示：

下面的例子显示两个地图，一个是基于美国地理编码为“Toledo”默认的地区（美国）“托莱多，俄亥俄州”，一个是基于西班牙显示的结果是“托莱多，西班牙”。

异步加载Javascript API
一般来说，加载Javascript地图API只要您在页面包含一个加载API的<script>标记，执行应用程序之后，加载所需的脚本就已经被下载了。不过，虽然Javascript已经被解析，您的浏览器可能不呈页面的其他内容。在大多数情况下，这种延迟并不明显，但您可能希望在加载页面完毕后加载地图API Javascript代码。您可以根据需要加载地图API的Javascript。这是很简单在页面完成后响应window.onload事件后执行页面<script>标签内代码加载地图JavaScript API，但你必须另行指示地图JavaScript API的引导行为推迟执行，直到JavaScript API完成加载后再执行您的应用程序代码。你可以在使用回调参数。这个参数作为加载函数是否执行完成的标识。

下面的代码指示应用程序完全加载页面后加载地图API（使用在window.onload），并将地图JavaScript API写入到页面的<script>标记内。此外，我们指示该API在完全加载完成后再回调执行初始化函数。

function initialize() {
var myLatlng = new google.maps.LatLng(-34.397, 150.644);
var myOptions = {
    zoom: 8,
    center: myLatlng,
    mapTypeId: google.maps.MapTypeId.ROADMAP
}
var map = new google.maps.Map(document.getElementById("map_canvas"), myOptions);
}

function loadScript() {
var script = document.createElement("script");
script.type = "text/javascript";
script.src = "http://maps.google.com/maps/api/js?sensor=false&callback=initialize";
document.body.appendChild(script);
}

window.onload = loadScript;

查看示例(map-simple-async.html)

版本
在谷歌地图API团队会定期更新Javascript API并添加新功能，修复bug和进行性能改进。所有API的变化将向后兼容，确保如果你使用当前文档启动一个应用程序接口，该应用程序将继续不加修改的随着API更新。（注意：实验的功能并不包括在此保障范围，特别是在API文档中明确表明是实验的）。

版本类型
你可以使用JavaScript API v参数说明要求应用程序使用的地图加载哪个版本的API。目前支持两种选项：

最新的版本，设置 v=3 或者省略该参数。此版本反映了当前的版本，包括任何错误修复和新功能，因为它们都是公开发布的。

一个指定的版本，指明 V=3。数字表明特定的API。这些编号的版本可以是一个发行版本或冻结的版本（见下面）。

下面举例说明如何请求对应特定版本的地图JavaScript API：

http://maps.google.com/maps/api/js?v=3.1&sensor=true_or_false

每个季度，我们将公布一个新的版本编号（以下简称“发行版”），并发布它供公众使用。整个季度，我们将继续对这个版本的错误进行修复，在地图JavaScript API的修改日志进行记录，同时确保该功能保持稳定。当我们发布一个新版本编号，我们会“冻结”以前发行的版本，这意味着我们将不再进行更新和任何代码更改，包括错误修正，确保它是完全稳定的。我们每次推出新版本后，将冻结现有的版本确保只有一个新版本。应用程序请求的版本已经退休时将自动接收当前冻结的版本。

版本选择
下列准则在您的应用程序使用第三个版本的API时适用：

产品化的应用程序应该始终指定一个次要版本(如3.1,3.2)。

地图API适配器并不适用于目前最新的(开发)版本。地图API适配器应用程序必须使用当前的发布版本，更早的版本由适配器进行覆盖。

当开发一个新的地图API v3的应用程序，我们建议您选择最新发布的版本号（例如：3.2），然后继续使用，直到您在以后的时间需要添加额外的功能时再使用最新的版本。这样你正在使用的版本将随着您的应用程序开发成熟，直到新的版本被发布而冻结。

产品化的应用程序请求的版本等于或比当前冻结版本更新，应该对每季度发布一次的最新版本进行测试，以查明具有向后兼容性，需要在该版本中的任何不明问题得到解决后再使用。

各版本文档
文档将始终显示最新(开发)的版本。但是，每个版本，我们将保持提供一个单独的文档

Nightly Version (3.2) Reference 最新 3.2版本文档

Release Version (3.1) Reference 发布3.1版本文档

Frozen Version (3.0) Reference 冻结 3.0 版本文档

问题处理
如果您的代码似乎并没有正常工作，这里有一些办法可以帮助你解决问题：

寻找错别字。记住，JavaScript是区分大小写的语言。

使用JavaScript调试器。在Firefox浏览器中，您可以使用Venkman调试器或Firebug插件。在IE浏览器，您可以使用Microsoft脚本调试器。很多视频演示了如何使用各种调试工具。

发送问题到谷歌地图API V3小组。

本文来自CSDN博客，转载请标明出处：http://blog.csdn.net/wuqinglianga/archive/2010/09/06/5867318.aspx

秒客网

第一章：谷歌地图 Javascript API V3 基础

相关文章