地址和搜索词语的自动完成功能

注：服务器端内容库

本页面介绍通过 Google Maps JavaScript API 提供的客户端内容库。如果您想在服务器上使用 Google Places API 网络服务，请参阅 Node.js Client for Google Maps Services。该链接指向的页面还介绍了 Java Client、Python Client 和 Go Client for Google Maps Services。

弃用通知：高级数据 (Zagat)、types 参数、ID 和引用字段

通知：id 和 reference 字段自 2014 年 6 月 24 日起已弃用。这些字段已替换为新的地点 ID，后者是一种唯一标识地点并可用于检索地点信息的文本标识符。我们延长了通常持续一年的弃用期，因为我们正在研究可确保这一变更不会破坏现有代码的方法。我们将在更改 API 处理 id 和 reference 字段的方式之前至少 90 天在本页面上更新最终通知。我们推荐您更新代码，以尽快使用新的地点 ID，而不是使用 id 和 reference 字段。

简介

自动填充是 Google Maps JavaScript API 中 Places 内容库的一项功能。可以使用自动填充让您的应用具有 Google 地图搜索字段的提前键入搜索行为。当用户开始键入地址时，自动完成功能将填补余下内容。

入门指南

在 Google Maps JavaScript API 中使用 Places 内容库之前，首先要确保在为 Google Maps JavaScript API 设置的同一项目的 Google API Console 中启用 Google Places API Web Service。

要查看已启用 API 的列表，请执行以下操作：

转至 Google API Console。
点击 Select a project 按钮，然后选择为 Google Maps JavaScript API 设置的同一项目并点击 Open。
在 Dashboard 上的 API 列表中，寻找 Google Places API Web Service。
如果在列表中看到该 API，则大功告成。如果未列出该 API，请执行以下操作将其启用：
1. 在页面顶部，选择 ENABLE API 以显示 Library 标签。也可从左侧菜单中选择 Library。
2. 搜索 Google Places API Web Service，然后从结果列表中选择它。
3. 选择 ENABLE。流程完成时，Google Places API Web Service 即会出现在 Dashboard 上的 API 列表中。

加载内容库

Places 服务是一个独立于主 Maps JavaScript API 代码的自包含内容库。要使用此库中包含的功能，必须先在 Maps API bootstrap URL 中使用 libraries 参数加载该库。

<script type="text/javascript" src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places"></script>

如需了解详细信息，请参阅库概览。

使用限额和政策

配额

根据 Google Places API Web Service 的使用限额文档所述，Google Places API Web Service 和地点自动填充共享使用配额。这些使用限额在使用 Places Library in the Google Maps JavaScript API 时同样适用。每日使用量按客户端与服务器端请求次数之和计算。

政策

必须按照所介绍的适用于 Google Places API Web Service 的政策使用 Places Library in the Google Maps JavaScript API。

类摘要

该 API 提供了两种类型的自动完成小工具，您可以分别通过 Autocomplete 和 SearchBox 类来添加。此外，您还可以使用 AutocompleteService 类以编程方式检索自动完成的结果。

以下是可用类的摘要：

Autocomplete 会向网页添加一个文本输入字段，并监控该字段是否有字符输入。当用户输入文本时，自动完成功能会以下拉选取列表的形式返回预测地点。当用户从该列表中选择一个地点时，该地点的相关信息将返回给 autocomplete 对象，并且可以通过您的应用进行检索。请参阅以下详情。
SearchBox 也会向网页添加一个文本输入框，其方式与 Autocomplete 大致相同。区别如下：
- 主要区别在于选取列表中所显示的结果。SearchBox 提供了一个扩展的预测项列表，其中可以包括地点（在 Google Places API 中定义）以及建议的搜索词语。例如，如果用户输入“pizza in new”，选取列表可能会包括短语“pizza in New York, NY”以及各种披萨折扣店的名称。
- 在限定搜索范围方面，SearchBox 提供的选项比 Autocomplete 要少。在前者中，您可以使搜索偏向于某个给定的 LatLngBounds。在后者中，您可以将搜索限于某个特定的国家/地区和特定的地点类型，以及设置边界。
请参阅以下详情。
您可以创建一个 AutocompleteService 对象，从而以编程方式检索预测项。调用 getPlacePredictions() 来检索要匹配的地点，或者调用 getQueryPredictions() 来检索要匹配的地点以及建议的搜索词语。注：AutocompleteService 不会添加任何 UI 控件。上述方法将返回一个预测对象的数组。每个预测对象均包含预测的文本，以及参考信息和结果如何匹配用户输入的内容的详情。请参阅以下详情。

本页面的其余部分提供了有关如何使用上述类的用例示例和详情。

如何使用自动完成功能

此视频向您展示了如何使用自动完成功能，其中包括演示和代码示例。

示例：地址表单的自动完成功能

您的应用是否包括地址表单，如在线订单的送货地址、信用卡账单地址或出租车预订表格？自动完成功能可以帮助用户填写详情。

图 1 显示了一个自动完成文本字段，以及当用户输入搜索查询词语时提供的预测地点选取列表：

当用户从选取列表中选择地址时，您的应用可以填充该地址表单：

查看地址表单实用效果：查看示例 (places-autocomplete-addressform.html)。

请继续阅读以了解如何向网页添加自动完成功能。

示例：地图控件的自动完成功能

自动完成功能可以为用户提示信息，它作为地图应用的一部分非常有用，如图 3 所示：

显示部分城市搜索查询词语和要匹配的地点的自动完成文本字段。 — 图 3：自动填充文本字段和选取列表

查看其实用效果：查看示例 (places-autocomplete-hotelsearch.html)。

请继续阅读以了解如何向网页添加自动完成功能。

添加地点和地址自动完成功能

Autocomplete 会在您的网页上创建一个文本输入字段，在 UI 选取列表中提供预测地点，然后返回地点详情以响应 getPlace() 请求。选取列表中的每个条目均对应于单个地点（由 Google Places API 所定义）。

Autocomplete 的构造函数有两个参数：

text 类型的 HTML input 元素。这是自动完成服务将监控并将其结果附于其中的输入字段。
options 参数，它可以包含下列属性：
- types 数组指定某个明确的类型或类型集合，支持的类型详见下文。若未指定任何类型，系统将返回所有类型。一般仅允许指定一种类型。例外情况是您可以安全地混用 geocode 和 establishment 类型，但是请注意，这样做的效果等同于未指定类型。支持的类型为：
  - geocode 指示“地点”服务仅返回地理编码结果，而不返回商家结果。
  - address 指示“地点”服务仅返回具有精确地址的地理编码结果。
  - establishment 指示“地点”服务仅返回商家结果。
  - (regions) 类型集合：指示“地点”服务返回匹配以下类型的任意结果：
    - locality
    - sublocality
    - postal_code
    - country
    - administrative_area1
    - administrative_area2
  - (cities) 类型集合指示“地点”服务返回匹配 locality 或 administrative_area3 的结果。
- bounds 是一个 google.maps.LatLngBounds 对象，用于指定要搜索地点的区域。其结果将偏向于但不限于这些边界内包含的地点。
- componentRestrictions 可以用来将结果限制在特定的群组。目前，您可以使用 componentRestrictions 按国家/地区进行过滤。country 必须传入一个与 ISO 3166-1 Alpha-2 兼容的双字符国家/地区代码。
- placeIdOnly 可用于指示 Autocomplete 小部件只检索地点 ID。调用 Autocomplete 对象上的 getPlace() 时，提供的 PlaceResult 将只有 place id、types 和 name 属性进行了设置。可以使用返回的地点 ID 来调用 Places、Geocoding、Directions 或 Distance Matrix 服务。
  注：name 属性将包含地点自动填充预测中的 description。可以在地点自动填充文档中阅读更多有关 description 的内容。

设置自动完成功能的偏向和搜索区域边界

您可以通过以下几种方式使自动完成结果偏向于某个大致位置或区域：

在创建 Autocomplete 对象时设置边界。
更改某个现有 Autocomplete 的边界。
将边界设置为地图的视口。
将搜索限制在某个特定的国家/地区内。

详情请见以下部分。

在创建 Autocomplete 对象时设置边界

以下示例使用 bounds 和 types 选项来请求类型为“establishment”（场所）的商家，且偏向于指定地理区域内的那些商家。

var defaultBounds = new google.maps.LatLngBounds(
  new google.maps.LatLng(-33.8902, 151.1759),
  new google.maps.LatLng(-33.8474, 151.2631));

var input = document.getElementById('searchTextField');
var options = {
  bounds: defaultBounds,
  types: ['establishment']
};

autocomplete = new google.maps.places.Autocomplete(input, options);

更改某个现有 Autocomplete 的边界

调用 setBounds() 来更改某个现有 Autocomplete 的搜索区域。

// Bias the autocomplete object to the user's geographical location,
// as supplied by the browser's 'navigator.geolocation' object.
function geolocate() {
  if (navigator.geolocation) {
    navigator.geolocation.getCurrentPosition(function(position) {
      var geolocation = {
        lat: position.coords.latitude,
        lng: position.coords.longitude
      };
      var circle = new google.maps.Circle({
        center: geolocation,
        radius: position.coords.accuracy
      });
      autocomplete.setBounds(circle.getBounds());
    });
  }
}

查看示例 (places-autocomplete-addressform.html)。

将边界设置为地图的视口

使用 bindTo() 可以使结果偏向于地图的视口，即使当该视口发生变化时也能够这样。

autocomplete.bindTo('bounds', map);

查看示例 (places-autocomplete.html)。

将搜索限制在某个特定的国家/地区内

使用 componentRestrictions 选项将自动完成搜索限制在某个特定的国家/地区内。以下代码将搜索结果限定为法国境内的城市。

var input = document.getElementById('searchTextField');
var options = {
  types: ['(cities)'],
  componentRestrictions: {country: 'fr'}
};

autocomplete = new google.maps.places.Autocomplete(input, options);

下面的示例允许用户选择一个国家/地区，然后将自动完成结果限制在该国家/地区范围内。

// Set the country restriction based on user input.
// Also center and zoom the map on the given country.
function setAutocompleteCountry() {
  var country = document.getElementById('country').value;
  if (country == 'all') {
    autocomplete.setComponentRestrictions([]);
    map.setCenter({lat: 15, lng: 0});
    map.setZoom(2);
  } else {
    autocomplete.setComponentRestrictions({'country': country});
    map.setCenter(countries[country].center);
    map.setZoom(countries[country].zoom);
  }
  clearResults();
  clearMarkers();
}

查看示例 (places-autocomplete-hotelsearch.html)。

定制自动完成功能的占位符文本

默认情况下，由自动完成服务创建的文本字段包含标准的占位符文本。要修改该文本，请设置 input 元素中的 placeholder 属性：

<input id="searchTextField" type="text" size="50" placeholder="Anything you want!">

注：默认的占位符文本会自动本地化。如果您指定自己的占位符值，则必须在应用中对该值进行本地化处理。如需了解有关 Google Maps JavaScript API 如何选择要使用的语言的信息，请阅读有关本地化的文档。

通过自动完成功能获取地点信息

当用户从附加到自动完成文本字段的预测项中选择某个地点时，该服务会触发 place_changed 事件。您可以调用 Autocomplete 对象中的 getPlace()，以获取 PlaceResult 对象。

默认情况下，自动完成功能将为您提供一个单行文本的详细地址。对于地址表单而言，获取结构化格式的地址是很有用的。您可以使用 Autocomplete.getPlace() 来获取每个自动完成预测项的完整详情，包括结构化的地址。

如果使用 placeIdOnly 选项，Autocomplete 对象将不会获取地点详情，因为 PlaceResult 对象仅设置了 place_id、types 和 name 属性。

注：name 属性将包含地点自动填充预测中的 description。可以在地点自动填充文档中阅读更多有关 description 的内容。

要获取地点详情，可通过在获取 place_changed 事件时调用 Autocomplete 对象上的 getPlace() 来检索 PlaceResult 对象。然后便可利用地理编码来获取位置坐标，或利用 Places 服务来获取有关所选地点的详细信息。

如需了解有关 PlaceResult 对象的详细信息，请参阅有关地点详细结果的文档。

以下示例使用自动完成功能来填写地址表单中的字段。

function fillInAddress() {
  // Get the place details from the autocomplete object.
  var place = autocomplete.getPlace();

  for (var component in componentForm) {
    document.getElementById(component).value = '';
    document.getElementById(component).disabled = false;
  }

  // Get each component of the address from the place details
  // and fill the corresponding field on the form.
  for (var i = 0; i < place.address_components.length; i++) {
    var addressType = place.address_components[i].types[0];
    if (componentForm[addressType]) {
      var val = place.address_components[i][componentForm[addressType]];
      document.getElementById(addressType).value = val;
    }
  }
}

查看示例 (places-autocomplete-addressform.html)。

添加 SearchBox 以自动完成搜索词语

SearchBox 允许用户执行基于文本的地理搜索，如“pizza in New York”或“shoe stores near robson street”。您可以将 SearchBox 附加到某个文本字段，当输入文本时，该服务将以下拉选取列表的形式返回预测项。

SearchBox 提供了一个扩展的预测项列表，其中可以包括地点（在 Google Places API 中定义）以及建议的搜索词语。例如，如果用户输入“pizza in new”，选取列表可能会包括短语“pizza in New York, NY”以及各种披萨折扣店的名称。当用户从该列表中选择某个地点时，有关该地点的信息将返回给 SearchBox 对象，并且可以通过您的应用进行检索。

SearchBox 的构造函数有两个自变量：

text 类型的 HTML input 元素。这是 SearchBox 服务将监控并将其结果附于其中的输入字段。
options 参数，它可以包含 bounds 属性：bounds 是一个 google.maps.LatLngBounds 对象，用于指定要搜索地点的区域。其结果将偏向于但不限于这些边界内包含的地点。

以下代码使用 bounds 参数将结果偏向于通过纬度/经度坐标指定的特定地理区域内的地点。

var defaultBounds = new google.maps.LatLngBounds(
  new google.maps.LatLng(-33.8902, 151.1759),
  new google.maps.LatLng(-33.8474, 151.2631));

var input = document.getElementById('searchTextField');

var searchBox = new google.maps.places.SearchBox(input, {
  bounds: defaultBounds
});

更改 SearchBox 的搜索区域

要更改某个现有 SearchBox 的搜索区域，请调用 SearchBox 对象中的 setBounds()，并传入相关的 LatLngBounds 对象。

查看示例 (places-searchbox.html)。

获取 SearchBox 信息

当用户从附加到搜索框的预测项中选择某个项目时，该服务会触发 places_changed 事件。您可以调用 SearchBox 对象中的 getPlaces()，以获取包含多个预测项的数组，其中每一项都是一个 PlaceResult 对象。

如需了解有关 PlaceResult 对象的详细信息，请参阅有关地点详细结果的文档。

// Listen for the event fired when the user selects a prediction and retrieve
// more details for that place.
searchBox.addListener('places_changed', function() {
  var places = searchBox.getPlaces();

  if (places.length == 0) {
    return;
  }

  // Clear out the old markers.
  markers.forEach(function(marker) {
    marker.setMap(null);
  });
  markers = [];

  // For each place, get the icon, name and location.
  var bounds = new google.maps.LatLngBounds();
  places.forEach(function(place) {
    if (!place.geometry) {
      console.log("Returned place contains no geometry");
      return;
    }
    var icon = {
      url: place.icon,
      size: new google.maps.Size(71, 71),
      origin: new google.maps.Point(0, 0),
      anchor: new google.maps.Point(17, 34),
      scaledSize: new google.maps.Size(25, 25)
    };

    // Create a marker for each place.
    markers.push(new google.maps.Marker({
      map: map,
      icon: icon,
      title: place.name,
      position: place.geometry.location
    }));

    if (place.geometry.viewport) {
      // Only geocodes have viewport.
      bounds.union(place.geometry.viewport);
    } else {
      bounds.extend(place.geometry.location);
    }
  });
  map.fitBounds(bounds);
});

查看示例 (places-searchbox.html)。

为自动完成功能和 SearchBox 小工具设置样式

默认情况下，由 Autocomplete 和 SearchBox 提供的 UI 元素被设置为可纳入 Google 地图中的样式。您可能需要调整样式以适合您自己的站点。提供了以下 CSS 类。下面列出的所有类均同时适用于 Autocomplete 和 SearchBox 小工具。

适用于 Autocomplete 和 SearchBox 小工具的 CSS 类的图解说明 — 适用于 Autocomplete 和 SearchBox 小工具的 CSS 类

CSS 类	说明
`pac-container`	包含由地点自动完成服务返回的预测项列表的视觉元素。此列表在 `Autocomplete` 或 `SearchBox` 小工具下方以下拉列表的形式出现。
`pac-icon`	预测项列表中显示在每个项目左侧的图标。
`pac-item`	由 `Autocomplete` 或 `SearchBox` 小工具提供的预测项列表中的项目。
`pac-item:hover`	用户将鼠标指针悬停在其上方的项目。
`pac-item-selected`	用户通过键盘选中的项目。注：选中的项目将是该类和 `pac-item` 类的成员。
`pac-item-query`	`pac-item` 中的一段内容，它是预测项的主要部分。对于地理位置，它包含了地点名称（如“Sydney”）或街道名称和门牌号码（如“10 King Street”）。对于基于文本的搜索，例如“pizza in New York”，它包含了查询的完整文本。默认情况下，`pac-item-query` 显示为黑色。如果 `pac-item` 中有任何附加文本，该文本将位于 `pac-item-query` 之外，并且继承 `pac-item` 的样式。默认情况下，它是灰色的。附加文本通常为地址。
`pac-matched`	返回的预测项中与用户输入的内容相匹配的部分。默认情况下，匹配的文本以粗体突出显示。请注意，匹配的文本可能位于 `pac-item` 中的任何位置。它不一定是 `pac-item-query` 的一部分，并且有可能一部分位于 `pac-item-query` 中，同时还有一部分在 `pac-item` 的剩余文本中。

通过自动完成服务检索预测项

要以编程方式检索预测项，请使用 AutocompleteService 类。AutocompleteService 不会添加任何 UI 控件。相反，它会返回一个预测对象的数组，每个对象均包含预测的文本、参考信息，以及结果如何匹配用户输入的内容的详情。如果您希望获得比上述 Autocomplete 和 SearchBox 所提供的界面控制方法更多的用户界面控制，这将非常有用。

AutocompleteService 公开了以下方法：

getPlacePredictions() 用来返回预测地点。注：如 Places API 中所定义的，“地点”可以是某个场所、地理位置或著名景点。
getQueryPredictions() 返回一个扩展的预测项列表，其中可以包括地点（在 Places API 中定义）以及建议的搜索词语。例如，如果用户输入“pizza in new”，选取列表可能会包括短语“pizza in New York, NY”以及各种披萨折扣店的名称。

上述两种方法均返回一个包含五个预测对象的数组，其形式如下：

description 是相匹配的预测项。
id 包含指示该地点的唯一标识符。此标识符可能无法用于检索有关此地点的信息，但是可用于合并有关此地点的数据，并在不同的搜索中验证地点的同一性。由于 ID 偶尔会变化，因此，建议您将存储的地点 ID 与后来针对同一地点的详情请求返回的 ID 进行比较，并在必要时进行更新。注：如本页面上的弃用通告中所述，id 已被弃用，取而代之的是 place_id。
matched_substrings 包含 description 中的一组子字符串，这些子字符串与用户输入的内容中的某些元素相匹配。这对于在您的应用中突出显示这些子字符串非常有用。在许多情况下，查询的关键字将显示为 description 字段的子字符串。
- length 是子字符串的长度。
- offset 是字符偏移量，从 description 字符串的开头开始数，它就是匹配的子字符串出现的位置。
place_id 是用于唯一标识地点的文本标识符。要检索有关该地点的信息，请在地点详情请求的 placeId 字段中传递此标识符。详细了解如何通过地点 ID 引用地点。
reference 包含可用于将来查询详情服务的令牌。此令牌可能与详情服务请求中使用的引用不同。建议您定期更新存储的地点引用。尽管此令牌唯一标识该地点，但是反之则不然：一个地点可以有多个有效的引用令牌。注：如本页面上的弃用通告中所述，reference 已被弃用，取而代之的是 place_id。
terms 是包含查询元素的数组。对于某个地点而言，每个元素通常都构成地址的一部分。
- offset 是字符偏移量，从 description 字符串的开头开始数，它就是匹配的子字符串出现的位置。
- value 是要匹配的词语。

以下示例针对短语“pizza near”执行了一次查询预测请求，并将结果显示在列表中。

// This example retrieves autocomplete predictions programmatically from the
// autocomplete service, and displays them as an HTML list.

// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">

function initService() {
  var displaySuggestions = function(predictions, status) {
    if (status != google.maps.places.PlacesServiceStatus.OK) {
      alert(status);
      return;
    }

    predictions.forEach(function(prediction) {
      var li = document.createElement('li');
      li.appendChild(document.createTextNode(prediction.description));
      document.getElementById('results').appendChild(li);
    });
  };

  var service = new google.maps.places.AutocompleteService();
  service.getQueryPredictions({ input: 'pizza near Syd' }, displaySuggestions);
}

<div id="right-panel">
  <p>Query suggestions for 'pizza near Syd':</p>
  <ul id="results"></ul>
</div>

/* Always set the map height explicitly to define the size of the div
 * element that contains the map. */
#map {
  height: 100%;
}
/* Optional: Makes the sample page fill the window. */
html, body {
  height: 100%;
  margin: 0;
  padding: 0;
}

#right-panel {
  font-family: 'Roboto','sans-serif';
  line-height: 30px;
  padding-left: 10px;
}

#right-panel select, #right-panel input {
  font-size: 15px;
}

#right-panel select {
  width: 100%;
}

#right-panel i {
  font-size: 12px;
}

<!-- Replace the value of the key parameter with your own API key. -->
<script type="text/javascript" src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&libraries=places&callback=initService"
    async defer></script>

// This example retrieves autocomplete predictions programmatically from the
// autocomplete service, and displays them as an HTML list.

// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">

function initService() {
  var displaySuggestions = function(predictions, status) {
    if (status != google.maps.places.PlacesServiceStatus.OK) {
      alert(status);
      return;
    }

    predictions.forEach(function(prediction) {
      var li = document.createElement('li');
      li.appendChild(document.createTextNode(prediction.description));
      document.getElementById('results').appendChild(li);
    });
  };

  var service = new google.maps.places.AutocompleteService();
  service.getQueryPredictions({ input: 'pizza near Syd' }, displaySuggestions);
}

查看示例 (places-queryprediction.html)。

一切就绪！

简介

入门指南

加载内容库

使用限额和政策

配额

政策

类摘要

如何使用自动完成功能

示例：地址表单的自动完成功能

示例：地图控件的自动完成功能

添加地点和地址自动完成功能

设置自动完成功能的偏向和搜索区域边界

在创建 Autocomplete 对象时设置边界

更改某个现有 Autocomplete 的边界

将边界设置为地图的视口

将搜索限制在某个特定的国家/地区内

定制自动完成功能的占位符文本

通过自动完成功能获取地点信息

添加 SearchBox 以自动完成搜索词语

更改 SearchBox 的搜索区域

获取 SearchBox 信息

为自动完成功能和 SearchBox 小工具设置样式

通过自动完成服务检索预测项

发送以下问题的反馈：

一切就绪！

激活 Google Maps JavaScript API

地址和搜索词语的自动完成功能

简介

入门指南

加载内容库

使用限额和政策

配额

政策

类摘要

如何使用自动完成功能

示例：地址表单的自动完成功能

示例：地图控件的自动完成功能

添加地点和地址自动完成功能

设置自动完成功能的偏向和搜索区域边界

在创建 Autocomplete 对象时设置边界

更改某个现有 Autocomplete 的边界

将边界设置为地图的视口

将搜索限制在某个特定的国家/地区内

定制自动完成功能的占位符文本

通过自动完成功能获取地点信息

添加 SearchBox 以自动完成搜索词语

更改 SearchBox 的搜索区域

获取 SearchBox 信息

为自动完成功能和 SearchBox 小工具设置样式

通过自动完成服务检索预测项

发送以下问题的反馈：