Google Maps JavaScript API V3 控件

1. 地图控件概述
2. 默认用户界面
   1. 默认控件集
   2. 停用默认用户界面
3. 向地图添加控件
4. 控件选项
   1. 修改控件的显示
   2. 控件定位
5. 自定义地图控件
   1. 定位自定义地图控件
   2. 绘制自定义地图控件
   3. 处理自定义地图控件的事件
   4. 自定义地图控件示例
   5. 向地图控件添加状态

控件概述

Google Maps 上的地图包含用户界面元素，可以让用户通过地图进行交互。这些元素称为“控件”。您可以在 Google Maps API 应用程序中添加这些控件的多种组合。或者，您也可以不进行任何操作，让 Google Maps API 处理所有控件行为。

Google Maps API 带有大量可以在地图中使用的内置控件：

• 缩放控件会显示一个滑块（对于大型地图）或小型的“+/-”按钮（对于小型地图），用于控制地图的缩放级别。在非触摸的设备上，该控件默认显示在地图的左上角，而在触摸设备上则会出现在左下角。
• 平移控件显示了用于平移地图的按钮。在非触摸的设备上，该控件默认显示在地图的左上角。您还可以使用平移控件对图像进行 45° 旋转（如果可用的话）。
• 比例控件，用于显示地图比例元素。默认情况下，系统不会启用此控件。
• MapType 控件，可让用户在不同的地图类型（例如 ROADMAP 和 SATELLITE）之间进行切换。该控件默认显示在地图的右上角。
• Street View 控件包含一个街景小人图标，将该图标拖动到地图上即可启用 Street View。该控件默认显示在地图的左上角。
• 旋转控件包含一个较小的圆形图标，可让您旋转包含斜面图像的地图。该控件默认显示在地图的左上角（有关详情，请参见 45° 图像）。
• 总览图控件会显示一个简略的总览图，用于在更广阔区域内反映当前的地图视口。该控件默认以压缩状态显示在地图的右下角。

请注意：以前提供的导航控件已弃用，系统已将其分割为独立的缩放和平移控件。

您无法直接访问或修改这些地图控件，而应修改地图的 MapOptions 字段，这些字段会影响控件的可见性和显示方式。您可以在初始化地图时调整控件的显示（使用适当MapOptions），或者通过调用 setOptions() 以更改地图的选项，对地图进行动态修改。

默认情况下，系统并不会启用所有这些控件。要了解有关默认用户界面行为（以及如何修改此类行为）的信息，请参阅下面的默认用户界面部分。

默认用户界面

您可能只想指定自己的地图展示 Google Maps 界面的外观（其中包括以后要添加到地图中的所有新特征或控件），而不想指定和设置单独的控件。要实现此行为，您无需进行任何操作。地图将会显示默认控件。

默认控件集

Google Maps API 提供了以下默认控件：

控件大屏幕小屏幕iPhoneAndroid缩放大型缩放控件，适用于 400x350 像素以上的屏幕小型缩放控件，适用于 400x350 像素以下的屏幕不显示。缩放是通过两根手指的开合操作来实现的。“触摸”式控件平移对 400x350 像素以上的屏幕显示对 400x350 像素以下的屏幕不显示不显示。平移是通过触摸来实现的。不显示。平移是通过触摸来实现的。MapType水平栏，适用于宽度在 320 像素以上的屏幕下拉菜单，适用于宽度在 320 像素以下的屏幕与大屏幕/小屏幕相同与大屏幕/小屏幕相同比例不存在不存在不存在不存在

此外，默认情况下，系统对所有设备都启用了键盘处理功能。

停用默认用户界面

有时，您可能希望关闭 API 的默认用户界面设置。要进行上述操作，请将 Map 的 disableDefaultUI 属性（在Map options 对象中）设置为 true。此属性可停用 Google Maps API 中所有自动执行的用户界面行为。

以下代码可彻底停用默认用户界面：

function initialize() {  var myOptions = {    zoom: 4,    center: new google.maps.LatLng(-33, 151),    disableDefaultUI: true,    mapTypeId: google.maps.MapTypeId.ROADMAP    }  var map = new google.maps.Map(document.getElementById("map_canvas"),       myOptions);}

查看示例 (control-disableUI.html)

向地图添加控件

您可能想要通过删除、添加或修改用户界面行为或控件调整您的界面，并确保即使以后进行了更新，也不会改变这种行为。如果您只想添加或修改现有的行为，您需要确保以显式的方式将相应的控件添加到自己的应用程序中。

有些控件在默认情况下会出现在地图上，而其他控件则只有在您明确提出相关请求后，才会显示出来。在地图中添加控件，或者从地图中删除控件都是在以下 Map options 对象的字段中指定的，您可以将这些字段设置为true 以显示相应的控件，或者设置为 false 以隐藏相应的控件：

{  panControl: boolean,  zoomControl: boolean,  mapTypeControl: boolean,  scaleControl: boolean,  streetViewControl: boolean,  overviewMapControl: boolean}

以下示例对地图进行了设置，使其隐藏导航（缩放和平移）控件，同时显示比例控件。请注意，我们并未显式停用默认用户界面，因此，您可在默认用户界面行为中加入这些修改。

function initialize() {  var myOptions = {    zoom: 4,    center: new google.maps.LatLng(-33, 151),    panControl: false,    zoomControl: false,    scaleControl: true,    mapTypeId: google.maps.MapTypeId.ROADMAP  }  var map = new google.maps.Map(document.getElementById("map_canvas"),        myOptions);}

查看示例 (control-simple.html)

控件选项

有些控件是可以配置的，这样，您就可以更改它们的行为或外观。例如，缩放控件可显示为带有滑块的大型完整控件，也可以显示为适用于较小地图的小型迷你缩放控件。

您可以在创建地图时更改 MapOptions 对象内适当的控件选项字段，从而对这些控件进行修改。例如，用于更改缩放控件的选项位于zoomControlOptions 字段中。

缩放控件可能出现在以下某个 style 选项中：

• google.maps.ZoomControlStyle.SMALL，用于显示迷你缩放控件，其中仅限 ＋ 和－ 按钮。此样式适用于小型地图。在触摸设备上，该控件显示为可响应触摸事件的 + 和 - 按钮。
• google.maps.ZoomControlStyle.LARGE 用于显示标准缩放滑块控件。在触摸设备上，该控件显示为可响应触摸事件的+ 和 - 按钮。
• google.maps.ZoomControlStyle.DEFAULT 会按照地图大小和运行地图的设备来挑选合适的缩放控件。

MapType 控件可显示为以下 style 选项之一：

• google.maps.MapTypeControlStyle.HORIZONTAL_BAR，用于在水平栏中将一组控件显示为如 Google Maps 中所示按钮。
• google.maps.MapTypeControlStyle.DROPDOWN_MENU，用于显示单个按钮控件，以便您从下拉菜单中选择地图类型。
• google.maps.MapTypeControlStyle.DEFAULT，用于显示“默认”的行为，该行为取决于屏幕尺寸，并且可能会在 API 以后的版本中有所变化。

请注意，如果您确实想要修改任何控件选项，您还是应当通过将 MapOptions 值设置为 true 以显式地启用相应的控件。例如，要将缩放控件设置为显示SMALL 样式，请在 MapOptions 对象内使用以下代码：

  ...  zoomControl: true,  zoomControlOptions: {    style: google.maps.ZoomControlStyle.SMALL  }  ...

以下示例设置了一个下拉 MapType 控件，并指定缩放控件使用小型迷你缩放布局：

function initialize() {  var myOptions = {    zoom: 4,    center: new google.maps.LatLng(-33, 151),    mapTypeControl: true,    mapTypeControlOptions: {      style: google.maps.MapTypeControlStyle.DROPDOWN_MENU    },    zoomControl: true,    zoomControlOptions: {      style: google.maps.ZoomControlStyle.SMALL    },    mapTypeId: google.maps.MapTypeId.ROADMAP  }  var map = new google.maps.Map(document.getElementById("map_canvas"),      myOptions);}

查看示例 (control-options.html)

控件通常是在创建地图时配置的。但是，您可以通过调用 Map 的 setOptions() 方法并为其传递新的控件选项动态更改控件的显示。

修改控件

您可以在创建地图时通过地图的 MapOptions 对象中的字段指定控件的显示。下面对这些字段进行了说明：

• mapTypeControl 可启用/停用“地图类型”控件，该控件允许用户在地图类型（如“地图”和“卫星”）之间切换。默认情况下，此控件将显示在地图右上角。mapTypeControlOptions 字段可进一步指定要用于此控件的MapTypeControlOptions。
• panControl 可启用/停用平移控件。默认情况下，此控件将显示在地图左上角。panControlOptions 字段可进一步指定要用于此控件的PanControlOptions。
• zoomControl 可启用/停用缩放控件。默认情况下，此控件将显示在地图左上角。zoomControlOptions 字段可进一步指定要用于此控件的ZoomControlOptions。
• scaleControl 可启用/停用“比例”控件，该控件可提供一个简单的地图比例尺。默认情况下，不会显示此控件。启用后，它将显示在地图的左下角。scaleControlOptions 可进一步指定用于此控件的ScaleControlOptions。
• rotateControl 可决定显示/不显示用于控制 45° 图像方向的旋转控件。默认情况下，该控件是否显示取决于指定的地图类型在当前缩放级别和位置上是否存在 45° 图像。要更改控件的行为，您可以设置地图的rotateControlOptions 以指定要使用的 RotateControlOptions（不过，如果当前没有可用的 45° 图像，则无法显示该控件）。
• overviewMapControl 可启用/停用总览图控件。总览图控件可以显示为完整的控件（展示简略的总览图），也可以显示为压缩的最小化状态。默认情况下，该控件处于停用和压缩状态。overviewMapControlOptions 可进一步指定用于此控件的OverviewMapControlOptions。

请注意，您可以为您最初停用的控件指定选项。

控件定位

每个控件选项都包含一个 position 属性（类型为 ControlPosition），它指明要在地图上放置该控件的位置。控件的定位并不是绝对的；相反，API 会在给定的约束条件（如地图大小）下，通过围绕现有地图元素或其他控件“流动”控件以智能方式布局控件。注意：虽然 API 会尝试以智能方式排列控件，但这并不能保证控件不会叠加指定的复杂布局。

系统支持以下控件位置：

• TOP_CENTER 表示控件应沿着地图顶部中心放置。
• TOP_LEFT 表示控件应沿着地图顶部左侧放置，控件的任何子元素“流”向顶部中心。
• TOP_RIGHT 表示控件应沿着地图顶部右侧放置，控件的任何子元素“流”向顶部中心。
• LEFT_TOP 表示控件应沿着地图顶部左侧放置，但应位于所有 TOP_LEFT 元素的下方。
• RIGHT_TOP 表示控件应沿着地图顶部右侧放置，但应位于所有 TOP_RIGHT 元素的下方。
• LEFT_CENTER 表示控件应沿着地图左侧放置，位于 TOP_LEFT 和 BOTTOM_LEFT 位置的中间。
• RIGHT_CENTER 表示控件应沿着地图右侧放置，位于 TOP_RIGHT 和 BOTTOM_RIGHT 位置的中间。
• LEFT_BOTTOM 表示控件应沿着地图底部左侧放置，但应位于所有 BOTTOM_LEFT 元素的上方。
• RIGHT_BOTTOM 表示控件应沿着地图底部右侧放置，但应位于所有 BOTTOM_RIGHT 元素的上方。
• BOTTOM_CENTER 表示控件应沿着地图底部中心放置。
• BOTTOM_LEFT 表示控件应沿着地图底部左侧放置，控件的任何子元素“流”向底部中心。
• BOTTOM_RIGHT 表示控件应沿着地图底部右侧放置，控件的任何子元素“流”向底部中心。

请注意，这些位置可能会与用户界面元素的位置相冲突，而您无法修改用户界面元素（如版权和 Google 徽标）的位置。在这种情况下，控件将按照每个位置的逻辑说明“流动”，并显示在尽可能靠近指定位置的位置。

下面的示例显示了一个简单的地图，其中启用了位于不同位置的所有控件。

function initialize() {  var myOptions = {    zoom: 12,    center: new google.maps.LatLng(-28.643387, 153.612224),    mapTypeId: google.maps.MapTypeId.ROADMAP,    mapTypeControl: true,    mapTypeControlOptions: {        style: google.maps.MapTypeControlStyle.HORIZONTAL_BAR,        position: google.maps.ControlPosition.BOTTOM_CENTER    },    panControl: true,    panControlOptions: {        position: google.maps.ControlPosition.TOP_RIGHT    },    zoomControl: true,    zoomControlOptions: {        style: google.maps.ZoomControlStyle.LARGE,        position: google.maps.ControlPosition.LEFT_CENTER    },    scaleControl: true,    scaleControlOptions: {        position: google.maps.ControlPosition.TOP_LEFT    },    streetViewControl: true,    streetViewControlOptions: {        position: google.maps.ControlPosition.LEFT_TOP    }  }  var map = new google.maps.Map(document.getElementById("map_canvas"),      myOptions);}

查看示例 (control-positioning.html)

自定义控件

除了修改现有 API 控件的样式和位置外，您还可以创建自己的控件以处理与用户的交互操作。控件是固定的窗口小部件，浮动在地图之上的绝对位置处；这与“叠加”不同，后者会随下面的地图一起移动。从本质上讲，控件只是一个在地图上具有绝对位置的<div> 元素，它会向用户显示某个用户界面，并处理与用户或地图的交互（通常通过某个事件处理程序）。

要创建您自己的自定义控件，没有什么需要遵循的“规则”。不过，您可以将以下指导原则视为最佳实践的参考：

• 为待显示的控件元素定义适当的 CSS。
• 针对地图属性更改或用户事件（如 'click' 事件），通过事件处理程序处理与用户或地图的交互。
• 创建一个 <div> 元素以承载控件并将此元素添加到 Map 的 controls 属性中。

下面将分别对上述原则加以说明。

绘制自定义控件

如何绘制控件由您自己决定。一般来讲，我们建议您将所有控件的显示方式放在一个单独的 <div> 元素中，以便可以将控件作为一个单元进行处理。我们将在下面所示的示例中使用这种设计模式。

设计具有吸引力的控件需要具备一些 CSS 和 DOM 结构方面的知识。以下代码显示了如何通过一个 <div> 容器、一个承载按钮轮廓的<div> 和另一个承载按钮内部事项的 <div> 创建一个简单的控件。

// Create a div to hold the control.var controlDiv = document.createElement('DIV');// Set CSS styles for the DIV containing the control// Setting padding to 5 px will offset the control// from the edge of the mapcontrolDiv.style.padding = '5px';// Set CSS for the control bordervar controlUI = document.createElement('DIV');controlUI.style.backgroundColor = 'white';controlUI.style.borderStyle = 'solid';controlUI.style.borderWidth = '2px';controlUI.style.cursor = 'pointer';controlUI.style.textAlign = 'center';controlUI.title = 'Click to set the map to Home';controlDiv.appendChild(controlUI);// Set CSS for the control interiorvar controlText = document.createElement('DIV');controlText.style.fontFamily = 'Arial,sans-serif';controlText.style.fontSize = '12px';controlText.style.paddingLeft = '4px';controlText.style.paddingRight = '4px';controlText.innerHTML = 'Home';controlUI.appendChild(controlText);

处理自定义控件的事件

要使控件有用，它必须能够实际完成某些任务。控件的用途由您确定。控件可以响应用户输入，也可以响应 Map 的状态变化。

为响应用户输入，Maps API 提供了一个跨浏览器的事件处理方法 addDomListener()，它可以处理浏览器的多数支持的 DOM 事件。以下代码段为浏览器的'click' 事件添加了一个侦听器。请注意，此事件是从 DOM 接收的，而不是从地图。

// Setup the click event listener: simply set the map to center on Chicagovar chicago = new google.maps.LatLng(41.850033, -87.6500523);google.maps.event.addDomListener(outer, 'click', function() {  map.setCenter(chicago)});

定位自定义控件

要在地图上定位自定义控件，您可以在 Map 对象的 controls 属性中将其放在适当位置。此属性包含一个google.maps.ControlPosition 数组。您可以通过将 Node（通常是 <div>）添加至适当ControlPosition 向地图中添加自定义控件。（有关这些位置的信息，请参见上面的控件定位。）

每个 ControlPosition 会存储一个显示在该位置的控件的 MVCArray。因此，当您向该位置添加或从中删除控件时，API 将相应更新控件。

API 按照 index 属性的顺序将控件放在每个位置，并会首先放置索引值较低的控件。例如，位置 BOTTOM_RIGHT 处的两个自定义控件将按照此索引顺序进行排列，并优先放置索引值较低的控件。默认情况下，所有自定义控件将在放置完任何 API 默认控件之后进行放置。您可以通过将控件的index 属性设置为一个负值覆盖此行为。请注意，如果希望在放置相同位置的默认 API 控件“之前”放置您的控件，通常只需设置一个索引值。

以下代码将创建一个新的自定义控件（未显示其构造函数）并将其添加到地图中的 TOP_RIGHT 位置。

var map = new google.maps.Map(document.getElementById('map_canvas'), mapOptions);// Construct your control in whatever manner is appropriate.// Generally, your constructor will want access to the// DIV on which you'll attach the control UI to the Map.var controlDiv = document.createElement('DIV');var myControl = new MyControl(controlDiv);// We don't really need to set an index value here, but// this would be how you do it. Note that we set this// value as a property of the DIV itself.controlDiv.index = 1;// Add the control to the map at a designated control position// by pushing it on the position's array. This code will// implicitly add the control to the DOM, through the Map// object. You should not attach the control manually.map.controls[google.maps.ControlPosition.TOP_RIGHT].push(controlDiv);

自定义控件示例

下面是一个简单的控件（尽管不是很实用），其中综合了上面所示的模式。该控件通过将地图在某个默认位置居中来响应 DOM 'click' 事件：

var map;var chicago = new google.maps.LatLng(41.850033, -87.6500523);/** * The HomeControl adds a control to the map that simply * returns the user to Chicago. This constructor takes * the control DIV as an argument. */function HomeControl(controlDiv, map) {  // Set CSS styles for the DIV containing the control  // Setting padding to 5 px will offset the control  // from the edge of the map  controlDiv.style.padding = '5px';  // Set CSS for the control border  var controlUI = document.createElement('DIV');  controlUI.style.backgroundColor = 'white';  controlUI.style.borderStyle = 'solid';  controlUI.style.borderWidth = '2px';  controlUI.style.cursor = 'pointer';  controlUI.style.textAlign = 'center';  controlUI.title = 'Click to set the map to Home';  controlDiv.appendChild(controlUI);  // Set CSS for the control interior  var controlText = document.createElement('DIV');  controlText.style.fontFamily = 'Arial,sans-serif';  controlText.style.fontSize = '12px';  controlText.style.paddingLeft = '4px';  controlText.style.paddingRight = '4px';  controlText.innerHTML = 'Home';  controlUI.appendChild(controlText);  // Setup the click event listeners: simply set the map to Chicago  google.maps.event.addDomListener(controlUI, 'click', function() {    map.setCenter(chicago)  });}function initialize() {  var mapDiv = document.getElementById('map_canvas');  var myOptions = {    zoom: 12,    center: chicago,    mapTypeId: google.maps.MapTypeId.ROADMAP  }  map = new google.maps.Map(mapDiv, myOptions);  // Create the DIV to hold the control and call the HomeControl() constructor  // passing in this DIV.  var homeControlDiv = document.createElement('DIV');  var homeControl = new HomeControl(homeControlDiv, map);  homeControlDiv.index = 1;  map.controls[google.maps.ControlPosition.TOP_RIGHT].push(homeControlDiv);}

查看示例 (control-custom.html)

为控件添加状态

控件也可以存储状态。下面的示例与前面所示的类似，但该控件包含了一个额外的“Set Home”按钮，它将控件设置为显示一个新首页位置。为此，我们在该控件内创建一个home_ 属性以存储此状态，并为该状态提供了获取函数和设置函数。

var map;var chicago = new google.maps.LatLng(41.850033, -87.6500523);/** * The HomeControl adds a control to the map that * returns the user to the control's defined home. */// Define a property to hold the Home stateHomeControl.prototype.home_ = null;// Define setters and getters for this propertyHomeControl.prototype.getHome = function() {  return this.home_;}HomeControl.prototype.setHome = function(home) {  this.home_ = home;}function HomeControl(map, div, home) {  // Get the control DIV. We'll attach our control UI to this DIV.  var controlDiv = div;  // We set up a variable for the 'this' keyword since we're adding event  // listeners later and 'this' will be out of scope.  var control = this;  // Set the home property upon construction  control.home_ = home;  // Set CSS styles for the DIV containing the control. Setting padding to  // 5 px will offset the control from the edge of the map  controlDiv.style.padding = '5px';  // Set CSS for the control border  var goHomeUI = document.createElement('DIV');  goHomeUI.title = 'Click to set the map to Home';  controlDiv.appendChild(goHomeUI);  // Set CSS for the control interior  var goHomeText = document.createElement('DIV');  goHomeText.innerHTML = 'Home';  goHomeUI.appendChild(goHomeText);    // Set CSS for the setHome control border  var setHomeUI = document.createElement('DIV');  setHomeUI.title = 'Click to set Home to the current center';  controlDiv.appendChild(setHomeUI);  // Set CSS for the control interior  var setHomeText = document.createElement('DIV');  setHomeText.innerHTML = 'Set Home';  setHomeUI.appendChild(setHomeText);  // Setup the click event listener for Home:  // simply set the map to the control's current home property.  google.maps.event.addDomListener(goHomeUI, 'click', function() {    var currentHome = control.getHome();    map.setCenter(currentHome);  });  // Setup the click event listener for Set Home:  // Set the control's home to the current Map center.  google.maps.event.addDomListener(setHomeUI, 'click', function() {    var newHome = map.getCenter();    control.setHome(newHome);  });}function initialize() {  var mapDiv = document.getElementById('map_canvas');  var myOptions = {    zoom: 12,    center: chicago,    mapTypeId: google.maps.MapTypeId.ROADMAP  }  map = new google.maps.Map(mapDiv, myOptions);  // Create the DIV to hold the control and call the HomeControl()  // constructor passing in this DIV.  var homeControlDiv = document.createElement('DIV');  var homeControl = new HomeControl(map, homeControlDiv, chicago);  homeControlDiv.index = 1;  map.controls[google.maps.ControlPosition.TOP_RIGHT].push(homeControlDiv);}