My favorites | 中文(简体) | Sign in

Mapplet 服务

  1. 服务概述
  2. 存储用户使用偏好
  3. 地址解析
    1. 地址解析对象
    2. 抽取结构化地址
  4. 检索外部内容
  5. KML 和 GeoRSS 叠加层
  6. 行车路线

服务概述

Google Mapplet API 会定期扩展，添加新的功能和特性，通常这些功能和特性会先在 ditu.google.cn 上发布。本部分讲述这些服务。注意：由于“服务”的定义在某种程度上较难懂，因此本部分会涉及的内容也较广。我们基本上将无法放到其他节的内容都放到了本部分中。

存储用户使用偏好

Google 小工具 API 的 setprefs 功能可让您在会话之间存储用户状态。要使用该功能，您的 Mapplet 应该包含：

  • <Require feature="setprefs"/> 标签（位于 <ModulePrefs> 下），用于通知小工具加载 setprefs 库。
  • 您要通过编程方式设置并永久存储其值的 Mapplet 说明中的 <UserPref> 标签。如果您为此 userpref 指定 hidden 数据类型，那么用户将不能直接编辑它。
  • 对 _IG_Prefs(__MODULE_ID__) 构造函数的调用。该对象具有获取和设置使用偏好的方法。

有关处理用户使用偏好的详细信息，请参见 Google 小工具 API 文档的处理 Userpref 数据类型部分。

以下示例具有计数器递增和重置计数器的按钮。如果您重新加载 Mapplet，会注意到计数器的值在该用户的不同对话间保持一致。

<?xml version="1.0" encoding="UTF-8" ?>
<Module>
  <ModulePrefs
    title="Set Userprefs Demo">
    <Require feature="sharedmap" />
    <Require feature="setprefs" />
  </ModulePrefs>
  <UserPref
    name="counter"
    default_value="0"
    datatype="hidden"/>
  <Content type="html">
  <![CDATA[
    <input type=button value="Increment Counter" onClick="incrementCounter();">
    <input type=button value="Reset Counter" onClick="resetCounter();">
    <div id="message" style="margin-top:1em"></span>

    <script>
     // Get user preferences
     var prefs = new _IG_Prefs(__MODULE_ID__);
     var message = document.getElementById("message");
     showCounter();

     // Show the current value of the counter
     function showCounter() {
       var counter = prefs.getInt("counter");
       message.innerHTML = "The counter value is " + counter;
     }

     // Increment value of "counter" user preference
     function incrementCounter() {
       var counter = prefs.getInt("counter");
       prefs.set("counter", counter + 1);
       showCounter();
     }

     // Reset value of "counter" userpref to 0
     function resetCounter(){
       prefs.set("counter", 0);
       showCounter();
     }
    </script>
  ]]>
  </Content>
</Module>

运行该示例 (setprefs.xml)

地址解析

地址解析是将地址（如“1600 Amphitheatre Parkway, Mountain View, CA”）转换为地理坐标（如经度 -122.083739 和纬度 37.423021）的过程，可以用于放置标记符或定位地图。

地址解析对象

还可以通过 GClientGeocoder 对象访问 Mapplet API 地址解析器。使用 GClientGeocoder.getLatLng() 将字符串地址转换为 GLatLng。此方法采用要转换的字符串地址以及在检索到地址后要执行的回调函数作为参数。该回调函数是必要的，因为地址解析涉及向 Google 的服务器发送请求，可能需要一些时间。

在此示例中，我们将对一个地址进行地址解析，在该点添加标记，并打开一个显示该地址的信息窗口。请注意，该回调函数作为函数显式声明传递。

var map = new GMap2();
var geocoder = new GClientGeocoder();
showAddress("76 9th ave new york");

function showAddress(address) {
  geocoder.getLatLngAsync(
    address,
    function(latlng) {
      if (!latlng) {
        alert("无法解析:" + address);
      } else {
        map.setCenter(latlng, 15);
        var marker = new GMarker(latlng);
        map.addOverlay(marker);
        marker.openInfoWindowHtml(address);
      }
    }
  );
}

运行该示例 (geocoding-simple.xml)

如果您需要从 Mapplet 外部访问地址解析器，那么请参见标准 Google 地图 API 的通过 HTTP 进行地址解析部分。

抽取结构化地址

如果要访问有关某个地址的结构化信息，GClientGeocoder 还提供了 getLocations() 方法，该方法返回包括以下信息的 JSON 对象：

  • Status
    • request - 请求类型。在本例中，始终是 geocode。
    • code - 响应代码，类似于 HTTP 状态代码，指示地址解析请求是否成功。请参见状态代码完整列表。
  • Placemark - 如果地址解析器发现多个匹配项，则可能返回多个地标。
    • address - 格式化良好，大小写正确的地址版本。
    • AddressDetails - 格式化为 xAL（或可扩展地址语言，一种地址格式化的国际标准）的地址。
    • Accuracy - 表示指定地址的地址解析所能达到的精确度的属性。请参见可能值列表。
    • Point - 3D 空间中的点，由 coordinates 值构成 - 地址的经度、纬度和海拔。在本例中，海拔始终设置为 0。

    下面我们展示使用地址解析器解析 Google 总部地址返回的 JSON 对象：

    {
  "name": "1600 Amphitheatre Parkway, Mountain View, CA, USA",
  "Status": {
    "code": 200,
    "request": "geocode"
  },
  "Placemark": [
    {
      "address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "AddressDetails": {
        "Country": {
          "CountryNameCode": "US",
          "AdministrativeArea": {
            "AdministrativeAreaName": "CA",
            "SubAdministrativeArea": {
              "SubAdministrativeAreaName": "Santa Clara",
              "Locality": {
                "LocalityName": "Mountain View",
                "Thoroughfare": {
                  "ThoroughfareName": "1600 Amphitheatre Pkwy"
                },
                "PostalCode": {
                  "PostalCodeNumber": "94043"
                }
              }
            }
          }
        },
        "Accuracy": 8
      },
      "Point": {
        "coordinates": [-122.083739, 37.423021, 0]
      }
    }
  ]
}

    在此示例中，我们使用 getLocations() 方法对地址进行地址解析，从 JSON 抽取地址的良好格式化版本和两个字母的国家或地区代码，并在信息窗口中显示。

    var map = new GMap2();;
map.setCenter(new GLatLng(34, 0), 1);
var geocoder = new GClientGeocoder();;

function addAddressToMap(response) {
  map.clearOverlays();
  if (!response || response.Status.code != 200) {
    alert("\"" + address + "\" not found");
  } else {
    place = response.Placemark[0];
    point = new GLatLng(place.Point.coordinates[1],
    place.Point.coordinates[0]);
    marker = new GMarker(point);
    map.addOverlay(marker);
    marker.openInfoWindowHtml(place.address + '<br>' +
      '<b>Country code:</b> ' + place.AddressDetails.Country.CountryNameCode);
  }
}

// showLocation() is called when you click on the Search button
// in the form.  It geocodes the address entered into the form
// and adds a marker to the map at that location.
function showLocation() {
  var address = document.forms[0].q.value;
  geocoder.getLocationsAsync(address, addAddressToMap);
}

// findLocation() is used to enter the sample addresses into the form.
function findLocation(address) {
  document.forms[0].q.value = address;
  showLocation();
}

    运行该示例 (geocoding-extraction.xml)

    检索外部内容

    小工具 API 文档的处理远程内容部分中的所有调用都在 Mapplet 中运行。

    • _IG_FetchContent(url, callback) -- 将url中的内容以文本形式返回。使用此功能来抓取 HTML 或纯文本内容。
    • _IG_FetchXmlContent(url, callback) -- 将url中的 XML 内容作为 DOM 对象返回并对其进行操作。使用此功能来抓取必须解析的 XML 内容。

    假设您具有以下 XML 文件（位于 http://mapgadgets.googlepages.com/cta_red.xml），该文件列出了芝加哥高速运输管理局红色铁路线的坐标。带名称的点就是车站的位置。

    <?xml version="1.0" encoding="UTF-8" ?> 
<points>
  <point lng="-87.67283499240875" lat="42.019110918045044">Howard</point> 
  <point lng="-87.66907453536987" lat="42.01585473134908">Jarvis</point> 
  <point lng="-87.66744375228882" lat="42.014483688722116" /> 
  <point lng="-87.66716480255127" lat="42.014228607763144" /> 
  <point lng="-87.66695022583008" lat="42.01400541108485" /> 
  <point lng="-87.66682147979736" lat="42.01379815632509" /> 
  <point lng="-87.66662836074829" lat="42.01357495813621" /> 
  <point lng="-87.66645669937134" lat="42.0133198735327" /> 
  <point lng="-87.66634941101074" lat="42.013080730787806" /> 
  <point lng="-87.66611337661743" lat="42.01263432859157" /> 
  <point lng="-87.6660704612732" lat="42.012283581810934" /> 
  <point lng="-87.66602754592896" lat="42.01188500357604" /> 
  <point lng="-87.66602754592896" lat="42.008010693009815">Morse</point> 
  <!-- ... -->
</points>

    以下示例使用 _IG_FetchXmlContent() 来下载和解析 XML 文件，然后画出铁路线并为每个车站添加标记。

    var map = new GMap2();

// Go to Chicago
map.setCenter(new GLatLng(41.882853, -87.642059), 11);   

// Render the red train line and stations from a remote XML file
var url = "http://mapgadgets.googlepages.com/cta_red.xml";
_IG_FetchXmlContent(url, function(response) {
  var trainline = [];
  var points = response.getElementsByTagName("point");

  for (var i = 0; i < points.length; i++) {
    var point = points.item(i);
    var lat  = point.getAttribute("lat");
    var lng  = point.getAttribute("lng");
    var latlng = new GLatLng(lat, lng);

    trainline.push(latlng);
    if (point.firstChild) {
      var station = point.firstChild.nodeValue;
      var marker = createMarker(latlng, station);
      map.addOverlay(marker);
    }
  }

  var polyline = new GPolyline(trainline, "#ff0000", 3, 1);
  map.addOverlay(polyline);
});

// Creates a marker at the given point with the given name
function createMarker(point, name) {
  var marker = new GMarker(point);
  GEvent.addListener(marker, "click", function() {
    marker.openInfoWindowHtml(name);
  });
  return marker;
}

    运行此示例 (remotecontent.xml)

    注意：_IG_FetchContent 和 _IG_FetchXmlContent 调用会自动缓存内容以减少服务器上的负载。请参见小工具 API 文档的刷新缓存部分，来了解关于更改缓存期限或禁用缓存的信息。

    KML/GeoRSS 叠加层

    我们建议以 KML 或 GeoRSS 数据格式存储数据，而不要使用 Javascript 添加点。使用 GGeoXml 对象将这些数据格式添加到地图，该对象的构造函数采用可公开访问的 XML 文件的网址。GGeoXml 地标显示为 GMarker，而 GGeoXml 折线和多边形显示为 Google 地图 API 折线和多边形。KML 文件中的 <GroundOverlay> 元素显示为地图上的 GGroundOverlay 元素。

    使用 addOverlay() 方法将 GGeoXml 对象添加到地图。（您可以使用 removeOverlay() 从地图中删除它们。）KML 和 GeoRSS XML 文件均受支持。

    以下示例在 http://mapgadgets.googlepages.com/cta.kml（在 Google 地图中查看）显示了所有芝加哥高速运输管理局铁路线。注意与使用 _IG_FetchXmlContent 的上个示例相比，这个简单了多少。

    var map = new GMap2();
var geoXml = new GGeoXml("http://mapgadgets.googlepages.com/cta.kml");

map.setCenter(new GLatLng(41.882853, -87.642059), 11);
map.addOverlay(geoXml);

    运行此示例 (ggeoxml.xml)

    行车路线

    您可以使用 GDirections 对象向自己的 Mapplet 添加行车路线。GDirections 对象使用查询字符串（例如“New York, NY to Chicago, IL”）或提供的文本经纬度（例如“40.712882, -73.967257 to 41.943181,-87.770677”）请求和接收行车路线结果。GDirections 对象还支持使用一系列点的多段行车路线。行车路线可显示为在地图上画出路线的折线，或作为 JSON 结构检索。

    要使用 Google 地图 API 中的行车路线，请创建 GDirections 类型的对象，并指定 GMap2 对象接收并显示结果。默认情况下，地图居中并且通过返回的路线限制边界（尽管可以在 GDirectionOptions 对象中使用参数进行更改）。

    行车路线使用 GDirections.load() 方法请求。此方法取查询字符串和一组可选的 GDirectionsOptions 参数。如果 GDirections 对象使用提供的 GMap2 对象构建，则返回的行车路线将包含折线叠加层。

    请注意行车路线对象不会立即填充此返回信息。。因此，GDirections 对象定义了一个“load”事件，以截获该事件来确定此状态。

    返回行车路线后，GDirections 对象内部会存储结果，可以使用 GDirections.getPolyline() 和/或 GDirections.getRoute(i:Number) 方法检索结果。可以使用 GRoute.getStep(i:Number) 方法检索路线中的路段，使用 GStep.getDescriptionHtml() 方法检索该路段的 HTML 摘要。

    // Create a directions object and register a map to hold the 
// resulting computed directions

var map;
var directions;

function initialize() {
  map = new GMap2();
  map.setCenter(new GLatLng(49.496675,-102.65625), 3);
  directions = new GDirections(map);
  directions.load("New York, NY to Chicago, IL");
}

    GDirections 对象还支持多点的行车路线，可以使用 GDirections.loadFromWaypoints() 方法构建。此方法取文本输入地址或文本经纬度点的数组。来自每个路标序列的行车路线均作为独立的路线计算，并在独立的 GRoute 对象中返回，其中每个均包含一系列 GStep 对象。

    GRoute 对象存储该路线的路段（类型为 GStep）数目、路线的起点和终点地址解析以及计算出的其他信息，如距离、历时和终点的精确经纬度（如果地址解析不依赖于路段，则可能与终点地址解析不同）。每个 GStep 对象还包含文本描述（例如“通过到 San Jose 的斜道驶上 US-101 S”）以及计算出的信息，包括距离、历时和精确经纬度。

    GDirections 对象触发您可以截获的三个事件：

    • “load”：此事件在成功返回行车路线结果后，但在向地图添加任何叠加层元素之前触发。
    • “addoverlay”：此事件会在折线行车路线组件添加到地图后触发。
    • “error”：如果行车路线请求导致错误，则触发此事件。调用者可以使用 GDirections.getStatus() 获取有关该错误的详细信息。

    有关行车路线 API 包中的各个对象、方法和事件的完整文档，请参见 API 参考。

    运行此示例 (directions-simple.xml)